Skip to content

Commit 4ce5dcc

Browse files
remenoscodesremenoscodes
committed
feat: initial plugin — autonomous task management via git-native-issue
Claude Code plugin that replaces internal TaskCreate/TaskUpdate/TaskList with git-native-issue commands. Three-layer activation: UserPromptSubmit hook for ambient context injection, ambient skill with autonomous decision rules and full CLI reference, and 6 user-invocable slash commands (setup, create, issues, show, close, sync). Autonomous behavior: auto-create issues for multi-step work, auto-update with progress labels/comments, auto-close on task completion, and auto-sync with platform provider (GitHub/GitLab/Gitea) after mutations. Provider detected from git remote URL and cached in git config.
0 parents  commit 4ce5dcc

17 files changed

Lines changed: 1045 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "claude-git-native-issue",
3+
"metadata": {
4+
"description": "Git-native issue tracking integration for Claude Code"
5+
},
6+
"owner": {
7+
"name": "Emerson Soares",
8+
"url": "https://github.com/remenoscodes"
9+
},
10+
"plugins": [
11+
{
12+
"name": "claude-git-native-issue",
13+
"description": "Replace Claude's internal task management with git-native-issue. Distributed, offline-first issue tracking that travels with your code.",
14+
"source": "./plugins/claude-git-native-issue",
15+
"homepage": "https://github.com/remenoscodes/claude-git-native-issue"
16+
}
17+
]
18+
}

‎.github/workflows/validate.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Validate Plugin
2+
on:
3+
push:
4+
branches: [main]
5+
pull_request:
6+
branches: [main]
7+
8+
jobs:
9+
validate:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Validate marketplace.json syntax
15+
run: python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
16+
17+
- name: Validate plugin.json syntax
18+
run: python3 -c "import json; json.load(open('plugins/claude-git-native-issue/.claude-plugin/plugin.json'))"
19+
20+
- name: Validate hooks.json syntax
21+
run: python3 -c "import json; json.load(open('plugins/claude-git-native-issue/hooks/hooks.json'))"
22+
23+
- name: Check required plugin.json fields
24+
run: |
25+
python3 -c "
26+
import json
27+
data = json.load(open('plugins/claude-git-native-issue/.claude-plugin/plugin.json'))
28+
required = ['name', 'description', 'version', 'license']
29+
for field in required:
30+
assert field in data, f'Missing required field: {field}'
31+
print('All required fields present')
32+
"
33+
34+
- name: Check SKILL.md frontmatter
35+
run: |
36+
for f in plugins/claude-git-native-issue/skills/*/SKILL.md; do
37+
echo "Checking $f"
38+
head -1 "$f" | grep -q "^---" || (echo "Missing frontmatter in $f" && exit 1)
39+
done
40+
41+
- name: Validate hook script is executable
42+
run: test -x plugins/claude-git-native-issue/hooks/task-intercept.sh
43+
44+
- name: Validate hook script outputs valid JSON
45+
run: bash plugins/claude-git-native-issue/hooks/task-intercept.sh | python3 -c "import json, sys; json.load(sys.stdin)"
46+
47+
- name: Validate version matches CHANGELOG
48+
run: |
49+
VERSION=$(python3 -c "import json; print(json.load(open('plugins/claude-git-native-issue/.claude-plugin/plugin.json'))['version'])")
50+
grep -q "\[${VERSION}\]" CHANGELOG.md || (echo "Version $VERSION not found in CHANGELOG.md" && exit 1)
51+
echo "Version $VERSION found in CHANGELOG.md"

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.DS_Store
2+
*.swp
3+
*.swo
4+
*~
5+
.vscode/
6+
.idea/

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6+
7+
## [1.0.0] - 2026-02-22
8+
9+
### Added
10+
11+
- UserPromptSubmit hook for ambient task management context injection
12+
- Ambient skill (`git-issue-tracker`) with autonomous decision rules and full CLI reference
13+
- Setup skill (`/claude-git-native-issue:setup`) for repo initialization
14+
- Create skill (`/claude-git-native-issue:create`) for issue creation
15+
- Issues skill (`/claude-git-native-issue:issues`) for listing with shorthands
16+
- Show skill (`/claude-git-native-issue:show`) for issue details
17+
- Close skill (`/claude-git-native-issue:close`) for closing issues
18+
- Sync skill (`/claude-git-native-issue:sync`) for remote and platform sync
19+
- CI validation workflow
20+
- README with installation guide and architecture overview

‎CONTRIBUTING.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Contributing
2+
3+
Contributions are welcome.
4+
5+
## Development
6+
7+
### Structure
8+
9+
```
10+
plugins/claude-git-native-issue/
11+
├── .claude-plugin/plugin.json # Plugin manifest
12+
├── hooks/
13+
│ ├── hooks.json # Hook definitions
14+
│ └── task-intercept.sh # UserPromptSubmit hook script
15+
└── skills/
16+
├── git-issue-tracker/SKILL.md # Ambient reference (non-user-invocable)
17+
├── setup/SKILL.md # /setup command
18+
├── create/SKILL.md # /create command
19+
├── issues/SKILL.md # /issues command
20+
├── show/SKILL.md # /show command
21+
├── close/SKILL.md # /close command
22+
└── sync/SKILL.md # /sync command
23+
```
24+
25+
### Adding a New Skill
26+
27+
1. Create a directory under `plugins/claude-git-native-issue/skills/<name>/`
28+
2. Add a `SKILL.md` with YAML frontmatter:
29+
```yaml
30+
---
31+
name: <name>
32+
description: <when this skill should activate>
33+
disable-model-invocation: true # for user-invocable skills
34+
---
35+
```
36+
3. Write step-by-step instructions in the body
37+
4. Update CHANGELOG.md with the new feature
38+
5. Bump version in `plugin.json`
39+
40+
### Skill Types
41+
42+
- **Ambient** (`user-invocable: false`): Claude invokes automatically when context matches the description
43+
- **User-invocable** (`disable-model-invocation: true`): User calls via `/claude-git-native-issue:<name>`
44+
45+
### Testing
46+
47+
Run the CI validation locally:
48+
49+
```bash
50+
# Validate JSON files
51+
python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
52+
python3 -c "import json; json.load(open('plugins/claude-git-native-issue/.claude-plugin/plugin.json'))"
53+
python3 -c "import json; json.load(open('plugins/claude-git-native-issue/hooks/hooks.json'))"
54+
55+
# Validate hook script output
56+
bash plugins/claude-git-native-issue/hooks/task-intercept.sh | python3 -c "import json, sys; json.load(sys.stdin)"
57+
58+
# Check SKILL.md frontmatter
59+
for f in plugins/claude-git-native-issue/skills/*/SKILL.md; do
60+
head -1 "$f" | grep -q "^---" && echo "OK: $f" || echo "FAIL: $f"
61+
done
62+
```
63+
64+
### Commits
65+
66+
This project uses [Conventional Commits](https://www.conventionalcommits.org/):
67+
68+
- `feat:` new skills, commands, or hook features
69+
- `fix:` bug fixes in existing skills
70+
- `docs:` README, CONTRIBUTING, CHANGELOG updates
71+
- `chore:` CI, tooling, metadata changes
72+
73+
## License
74+
75+
By contributing, you agree that your contributions will be licensed under GPL-2.0.

‎LICENSE‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This project is licensed under the GNU General Public License v2.0.
2+
3+
See https://www.gnu.org/licenses/old-licenses/gpl-2.0.html for the full license text.
4+
5+
SPDX-License-Identifier: GPL-2.0

‎README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# claude-git-native-issue
2+
3+
Claude Code plugin that replaces internal task management with [git-native-issue](https://github.com/remenoscodes/git-native-issue). Distributed, offline-first issue tracking stored as Git refs.
4+
5+
## What it does
6+
7+
This plugin teaches Claude to **autonomously** manage issues using `git issue` commands:
8+
9+
- **Auto-create** issues when multi-step work begins, plans are approved, or bugs are discovered
10+
- **Auto-update** issues with progress comments and status labels
11+
- **Auto-close** issues when tasks complete successfully
12+
- **Skip tracking** for trivial changes, questions, and exploratory work
13+
14+
It also provides slash commands for manual issue management.
15+
16+
## Prerequisites
17+
18+
- [git-native-issue](https://github.com/remenoscodes/git-native-issue) installed:
19+
```bash
20+
brew install remenoscodes/git-native-issue/git-native-issue
21+
```
22+
- A git repository (issues are stored as git refs)
23+
24+
## Installation
25+
26+
```bash
27+
# Add the marketplace
28+
/plugin marketplace add remenoscodes/claude-git-native-issue
29+
30+
# Install the plugin
31+
/plugin install claude-git-native-issue
32+
```
33+
34+
## Setup
35+
36+
After installing, run the setup skill in any git repository:
37+
38+
```
39+
/claude-git-native-issue:setup
40+
```
41+
42+
This will:
43+
1. Initialize git-native-issue in the repo
44+
2. Optionally configure auto-sync for issue refs
45+
3. Optionally add task management instructions to your CLAUDE.md
46+
47+
## Slash Commands
48+
49+
| Command | Description |
50+
|---------|-------------|
51+
| `/claude-git-native-issue:setup` | Initialize git-issue in repo and configure integration |
52+
| `/claude-git-native-issue:create` | Create a new issue |
53+
| `/claude-git-native-issue:issues` | List issues with filtering |
54+
| `/claude-git-native-issue:show` | Show issue details and comments |
55+
| `/claude-git-native-issue:close` | Close an issue |
56+
| `/claude-git-native-issue:sync` | Sync issues with remote or platform |
57+
58+
### Examples
59+
60+
```bash
61+
# Create an issue
62+
/claude-git-native-issue:create "Fix auth bug" -l bug -p high
63+
64+
# List in-progress issues
65+
/claude-git-native-issue:issues in-progress
66+
67+
# Show issue details
68+
/claude-git-native-issue:show a7f3b2c
69+
70+
# Close with message
71+
/claude-git-native-issue:close a7f3b2c -m "All tests passing"
72+
73+
# Sync with GitHub
74+
/claude-git-native-issue:sync github:owner/repo
75+
```
76+
77+
## How It Works
78+
79+
### Architecture
80+
81+
Three-layer activation (same pattern as [claude-language-coach](https://github.com/remenoscodes/claude-language-coach)):
82+
83+
1. **UserPromptSubmit hook** — injects context on every prompt, reminding Claude to use `git issue` and defining autonomous trigger rules
84+
2. **Ambient skill** (`git-issue-tracker`) — full CLI reference, autonomous decision rules, status conventions, error handling
85+
3. **User-invocable skills** — slash commands for convenience
86+
87+
### Autonomous Behavior
88+
89+
Claude creates, updates, and closes issues without being asked:
90+
91+
| Trigger | Action |
92+
|---------|--------|
93+
| User starts multi-step work | Create tracking issue |
94+
| Plan approved | Create issue(s) per work stream |
95+
| Bug discovered during work | Create bug issue |
96+
| Starting work on an issue | Add `in-progress` label |
97+
| Progress milestone | Add comment |
98+
| Task completed | Close issue |
99+
100+
### Status Convention
101+
102+
| Status | git-issue Representation |
103+
|--------|--------------------------|
104+
| Pending | `[open]` (no in-progress label) |
105+
| In Progress | `[open]` + `in-progress` label |
106+
| Completed | `[closed]` |
107+
| Blocked | `[open]` + `blocked` label |
108+
109+
## Why git-native-issue?
110+
111+
- **Distributed** — Issues travel with `git clone`, no central server needed
112+
- **Offline-first** — Works without network, syncs when ready
113+
- **No pollution** — Stored in `refs/issues/`, not in the working tree
114+
- **Auditable** — Full history via `git log refs/issues/<uuid>`
115+
- **AI-friendly** — Structured metadata, no rate limits, no API keys
116+
- **Standard tools** — Uses `git log`, `git for-each-ref`, standard trailers
117+
118+
## License
119+
120+
GPL-2.0 — same as git-native-issue.

‎plugins/claude-git-native-issue/.claude-plugin/plugin.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "claude-git-native-issue",
3+
"description": "Replace Claude's internal task management with git-native-issue. Autonomous issue creation, tracking, and resolution stored as Git refs. Distributed, offline-first, travels with your code.",
4+
"version": "1.0.0",
5+
"license": "GPL-2.0",
6+
"keywords": ["git", "issues", "tasks", "tracking", "distributed", "offline", "git-native-issue", "task-management"],
7+
"author": {
8+
"name": "Emerson Soares",
9+
"url": "https://github.com/remenoscodes"
10+
},
11+
"homepage": "https://github.com/remenoscodes/claude-git-native-issue",
12+
"repository": "https://github.com/remenoscodes/claude-git-native-issue"
13+
}

‎plugins/claude-git-native-issue/hooks/hooks.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"description": "Remind Claude to use git-issue for task tracking on every prompt",
3+
"hooks": {
4+
"UserPromptSubmit": [
5+
{
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/task-intercept.sh",
10+
"timeout": 5
11+
}
12+
]
13+
}
14+
]
15+
}
16+
}

‎plugins/claude-git-native-issue/hooks/task-intercept.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env bash
2+
3+
# git-native-issue task intercept — injected on every user prompt via UserPromptSubmit hook.
4+
# Reminds Claude to use `git issue` commands instead of internal TaskCreate/TaskUpdate/TaskList tools.
5+
# Also defines autonomous behavior: when to create/update/close issues without being asked.
6+
# Uses hookSpecificOutput.additionalContext for silent context injection (not shown to user).
7+
8+
cat << 'EOF'
9+
{
10+
"hookSpecificOutput": {
11+
"hookEventName": "UserPromptSubmit",
12+
"additionalContext": "git-native-issue is active. For ALL task tracking, use `git issue` commands via Bash instead of internal TaskCreate/TaskUpdate/TaskList tools. Quick reference: create → `git issue create \"title\" -m \"desc\" -l label -p priority`, list → `git issue ls`, show → `git issue show <id>`, progress → `git issue edit <id> --add-label in-progress`, close → `git issue state <id> --close -m \"reason\"`, search → `git issue search \"pattern\"`. AUTONOMOUS BEHAVIOR: (1) Auto-create issues when user starts multi-step work, approves a plan, or discovers a bug. (2) Auto-update with `--add-label in-progress` when starting work, `git issue comment` for progress. (3) Auto-close when task completes successfully. (4) Skip tracking for trivial changes, one-off questions, or when not in a git repo. (5) PLATFORM SYNC: After creating or closing issues, sync with the provider. Detect provider from git remote URL (github.com → github:owner/repo, gitlab.com → gitlab:group/project, gitea/forgejo → gitea:owner/repo). Run `git issue sync <provider>` after mutations. Check `git config --get git-issue.provider` for cached provider string. Before any git-issue command, verify you are in a git repo. If git-issue is not initialized, run `git issue init` first. Invoke the `git-issue-tracker` skill for full reference when needed."
13+
}
14+
}
15+
EOF
16+
exit 0

0 commit comments

Comments
 (0)