simple-issues

Files (1)

• SKILL.md

SKILL.md (first lines)

# File-Based Issue Tracker

A zero-infrastructure issue tracker that lives inside the repository under `.issues/`. Designed for workshops and small teams where multiple humans (each on their own machine, optionally with agents) collaborate without stepping on each other.

## 1. On activation — ALWAYS do this first

When this skill activates, immediately:

1. Check whether `.issues/` exists at the repo root.
    - If **not**, ask the user: _"No issue tracker found. Should I initialize `.issues/` here?"_ — then follow §2.
2. If it exists, scan all three folders and report to the user:
    - Count of issues in `open/`, `claimed/`, `closed/`.
    - List of **available** open issues (title + short-id), filtered to those whose `dependsOn` are all in `closed/`.
    - Whether **this machine** (see §3 for identity) currently has any issue in `claimed/` — if yes, name it. The agent must finish that one before claiming anything new.

Example report:

```
📋 Issue tracker status
  open: 4  |  claimed: 2  |  closed: 11

Available to claim (deps satisfied):
  - a3f1  Add dark mode toggle
  - 9b22  Refactor auth middleware

Currently claimed by this machine (yannick@thinkpad):
  - 7e04  Fix flaky login test  ← finish this before claiming a new one
```

## 2. Initializing the structure

```bash
mkdir -p .issues/open .issues/claimed .issues/closed
```

Add a short `.issues/README.md` explaining the workflow (optional but recommended). Do **not** add `.gitignore` entries — issues are meant to be committed.

## 3. Machine identity

Every claim is owned by a **machine**, not a person. Compute identity as:

```
<username>@<hostname>
```

- POSIX: `echo "$(whoami)@$(hostname -s)"`
- Windows: `echo "$env:USERNAME@$env:COMPUTERNAME"`

Cache this value for the session. Never invent or reuse another machine's identity.

## 4. Git awareness (optional)

Before any state-changing operation (claim, close, create), check if the repo uses git:

```bash
git rev-parse --is-inside-work-tree 2>/dev/null
```

- If **yes**: run `git pull --rebase` first to minimize claim races. If a rebase conflict touches `.issues/claimed/`, inform the user — another machine likely claimed the same issue.
- If **no** (workshop single-machine scenario): skip; just operate on the filesystem.

## 5. Issue file format

### Filename

```
<short-id>-<kebab-title>.md
```

- `short-id`: first **4 hex chars of the SHA-1** of the issue's initial markdown body (frontmatter excluded). Compute _before_ writing the file.
- `kebab-title`: lowercase, ASCII, hyphen-separated, max ~60 chars.

Example: `a3f1-add-dark-mode-toggle.md`

If a 4-char collision occurs (very rare in workshops), extend to 6 chars for the new file only.

### Frontmatter (YAML)

```yaml
---
title: "Add dark mode toggle"
dependsOn: [] # list of short-ids, e.g. ["9b22", "7e04"]
humanNeeded: false # true if ANY step requires a human to act, decide, or be interviewed
humanNeededReason: null # required free-text string when humanNeeded=true
claimedBy: null # "user@hostname" when in claimed/, else null
timestamp: 2026-05-18T12:34:56Z # ISO-8601 UTC, creation only — never updated
---
```

**Field rules**

| Field               | Mutable?                                      | Notes                                                                                       |
| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `title`             | No                                            | Set at creation.                                                                            |
| `dependsOn`         | No                                            | Set at creation. If deps change, add a Note explaining and modify as needed. |
| `humanNeeded`       | Yes (append-only context: flip + Note)        | May be toggled by any agent; must be accompanied by a Note.                                 |
| `humanNeededReason` | Yes (with `humanNeeded`)                      | Free-text.                                                                                  |
| `claimedBy`         | Yes (only on open→claimed and claimed→closed) | Set to machine id on claim; leave as-is on close.                                           |
| `timestamp`         | **Never**                                     | Creation time only.                                                                         |

### Body — append-only

```markdown
<Original description written at creation. NEVER edit or rewrite this.>

## Notes

### 2026-05-18T14:23:00Z — yannick@thinkpad

Discovered the bug also affects Safari 17. Scope unchanged.

### 2026-05-18T15:10:00Z — yannick@thinkpad

Resolution: fixed in commit abc1234. Closing.
```

**Strict Note format:**

```

From bakaschwarz/agent-skills, MIT.

More from bakaschwarz/agent-skills