project-issues

Files (1)

• SKILL.md

SKILL.md (first lines)

## Issue tracker selection

Read the canonical project setting before inspecting local artifacts:

```bash
ISSUE_TRACKER=$(python3 - <<'PY'
import pathlib, yaml
p = pathlib.Path('.sweetclaude/state/sweetclaude.yaml')
try:
    d = yaml.safe_load(p.read_text()) or {}
except (OSError, yaml.YAMLError):
    d = {}
print(d.get('project', {}).get('issue_tracker', 'local'))
PY
)
```

`project.issue_tracker` is `local` by default. If it is `github`, GitHub
Issues are the project system of record: do **not** read, create, migrate, or
sync `.sweetclaude/product` issue files. This includes skipping the local
migration guard below.

Only `local` and `github` are valid values. If the setting contains anything
else, report the invalid value and stop rather than guessing a tracker.

`tracker local` and `tracker github` explicitly change this per-project
setting. Treat clear natural-language requests as the same operation. For
example, “use GitHub for this project's issues”, “track issues on GitHub”, and
“stop using local issue tracking” mean `tracker github`; “use local issues
again” means `tracker local`. If the request is ambiguous about the project or
tracker, ask one clarification question rather than changing configuration.

Before changing to `github`, run the connection check below. Then update only
`project.issue_tracker` in `.sweetclaude/state/sweetclaude.yaml` with an atomic
replace; do not import, export, or delete issues as a side effect:

```python
import os, pathlib, tempfile, yaml

path = pathlib.Path('.sweetclaude/state/sweetclaude.yaml')
data = yaml.safe_load(path.read_text(encoding='utf-8')) or {}
data.setdefault('project', {})['issue_tracker'] = '<local-or-github>'
with tempfile.NamedTemporaryFile('w', dir=path.parent, suffix='.tmp',
                                 delete=False, encoding='utf-8') as tmp:
    yaml.safe_dump(data, tmp, default_flow_style=False, sort_keys=False,
                   allow_unicode=True)
    temp_path = tmp.name
os.replace(temp_path, path)
```

Confirm the selected system of record. Process this configuration operation
before routing the remaining arguments.

First verify the connection:

```bash
gh auth status 2>/dev/null && git remote get-url origin 2>/dev/null
```

If authentication or an `origin` remote is unavailable, explain which is
missing and stop. Never silently fall back to local issue files.

For `github`, route `$ARGUMENTS` directly to GitHub:

| Arguments | GitHub operation |
|---|---|
| (empty), `list`, `backlog` | `gh issue list --state open --limit 100` |
| `view <number>` | `gh issue view <number>` |
| `new` | Collect title and description one question at a time, then `gh issue create --title "..." --body "..."` |
| `update <number>` | Show `gh issue view <number>`, collect title/body/assignee/label changes, then use `gh issue edit` with only those fields |
| `close <number>` or `decline <number>` | Confirm when necessary, then `gh issue close <number>` |
| `reopen <number>` | `gh issue reopen <number>` |

Use GitHub issue numbers in this mode (for example, `#42` or `42`), not
`ISSUE-NNN`. `triage` is not a file move in GitHub mode: apply or remove the
repository's existing `triage` label with `gh issue edit`. Do not create labels
implicitly; if no suitable label exists, say so and leave the issue unchanged.
Report the GitHub URL returned by each mutation.

The local-only operations and rules below apply only when `ISSUE_TRACKER` is
`local`.

## MIGRATION GUARD

Before any other work, check for legacy migration/recovery risk:

```bash
PRODUCT_BASE=$(python3 -c "
import yaml, pathlib
p = pathlib.Path('.sweetclaude/artifact-privacy.yaml')
if p.exists():
    d = yaml.safe_load(p.read_text()) or {}
    base = d.get('categories', {}).get('product', {}).get('base_path', '')
    if base:
        print(base.rstrip('/'))
        exit()
print('.sweetclaude/product')
" 2>/dev/null || echo '.sweetclaude/product')
LEGACY_FILES=$(find "${PRODUCT_BASE}" -maxdepth 4 -type f \( -name 'BL-*.md' -o -name 'STORY-*.md' -o -name 'BUG-*.md' -o -name 'DEBT-*.md' -o -name 'CHORE-*.md' \) 2>/dev/null | wc -l | tr -d ' ')
if [ "$LEGACY_FILES" -gt 0 ]; then
  SCRIPT=${CLAUDE_PLUGIN_ROOT}/scripts/recovery/recover_project.py
  if [ ! -f "$SCRIPT" ]; then
    SCRIPT=$(find "$(dirname "${CLAUDE_PLUGIN_ROOT}")" -type f -path '*/scripts/recovery/recover_project.py' 2>/dev/null | sort -V | tail -1)
  fi
  if [ -n "$SCRIPT" ] && [ -f "$SCRIPT" ]; then
    python3 "$SCRIPT" guard --project-dir . --pretty
  else
    echo '{"status":"guard-unavailable","message":"Recovery guard unavailable. Run /sweetclaude:configure update before migration."}'
  fi
fi
```

If the guard output has `status` `run-recover`, `manual-review`,
`compatibility-mode`, `missing-product-base`, or `guard-unavailable`: print the
guard `message`, tell the user to run `/sweetclaude:configure recover` when recovery is
available, and stop. Do not recommend migration.

If the guard output has `status` `supported-migration-available`: print
"This project has a typed legacy backlog layout that can be migrated. Run

From carson-sweet/sweetclaude, AGPL-3.0.

More from carson-sweet/sweetclaude