@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/extra/skills/skill-maintenance/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: skill-maintenance
+description: "How to create and maintain agent skills, both project-local and shared: invoke when a workflow changes, a skill is missing or outdated, or something documented in a skill is found to be wrong."
+verified: 2026-10-31
+---
+
+# Skill Maintenance
+
+> Scope: this skill owns an individual `SKILL.md`: its format, frontmatter, and lifecycle.
+> For the structure around it (collection layout, naming, bundled scripts, local
+> development, and the Claude Code plugin/marketplace variant), read **`plugin-authoring`**.
+
+Skills are the authoritative documentation for how Claude does work in a repo. Keep them current.
+
+## When to act
+
+- A workflow, command, or process changed → update the relevant skill
+- A skill is wrong or misleading → fix it immediately, then continue
+- No skill covers something Claude just did or learned → create one
+- A tool, dependency, or task was added or removed → update the relevant skill
+
+Never leave a known-wrong skill in place. Fix it in the same session it's discovered, and every fix ends with [After every change](#after-every-change).
+
+## Where skills live
+
+Two kinds, and the difference decides what you must do after editing:
+
+- **Project-local:** `.claude/skills/<name>/SKILL.md` in the repo being worked on. Loads from the working copy.
+- **Shared:** a skill in a collection or plugin repo of its own, installed into `~/.claude/skills`, a plugin, or wherever that collection says. It loads from where it was installed, not from the copy you edit.
+
+Editing a shared skill changes nothing until the change reaches where it is installed. See [After every change](#after-every-change): that step is mandatory.
+
+## Skill file format
+
+Each skill is a **directory** containing a `SKILL.md`:
+
+```
+.claude/skills/<name>/SKILL.md
+```
+
+The directory name is the skill name. A flat `<name>.md` is not picked up: it must be `<name>/SKILL.md`.
+
+```markdown
+---
+name: kebab-case-name
+description: One-line summary: what it does and when to use it
+verified: YYYY-MM-DD
+---
+
+# Skill Title
+
+...content...
+```
+
+Set `verified:` to today's date whenever you create or update a skill.
+
+### Frontmatter must be strict YAML
+
+Claude Code parses frontmatter leniently. Every other agent uses a strict YAML parser and
+**silently skips a skill it cannot parse:** no error, the skill simply never appears.
+
+**Quote the description whenever it contains `: ` (colon-space), `#`, or starts with
+`"`, `'`, `[`, or `{`.** A plain scalar like this is invalid and will be dropped:
+
+```yaml
+description: Owns every decision: the entry point, the approval flow    # BROKEN
+description: "Owns every decision: the entry point, the approval flow"  # correct
+```
+
+Verify before committing: run the collection's own tests where it has them, and check every
+`SKILL.md` strictly (frontmatter present, `name` equal to its directory, and no plain value a
+strict YAML reader would reject).
+
+### Optional frontmatter
+
+- `disable-model-invocation: true`: keep the skill invocable via `/<name>` but prevent Claude from auto-loading it. Use for manual-only skills.
+- `allowed-tools: Bash(...)`: grant specific tool permissions while this skill is active, scoped to the skill's lifetime only.
+
+## Writing good skills
+
+- Write direct instructions, not background or commentary
+- Document the *why* only when it's non-obvious
+- Cover edge cases and failure modes, not just the happy path
+- A skill that needs a task describes *how to call it*: the task itself is the implementation
+
+## After every change
+
+Any edit to a shared skill (new skill, reworded description, one-word typo fix) is not live until it is released and installed. Do all three steps, every time, without being asked:
+
+1. **Commit it.** Never end a skill edit with the work sitting uncommitted:
+   - Stage the edited skill files: specific paths only, never `git add .`.
+   - Follow the repo's `CLAUDE.md` and the `git-workflow` skill for the rest: conventional message, committed without asking.
+   - Commit even a one-line fix, and even if the user didn't mention git.
+
+2. **Install it.** Once the change is released the way its collection releases (merged to its default branch, a new plugin version), update the installed copy the way it was installed (`npx skills update`, `claude plugin update`, the collection's own install), never by hand-copying into `~/.claude/skills` or `~/.agents/skills`.
+
+3. **Tell the user to restart Claude Code.** Say it explicitly as the last thing in the response, e.g. *"Restart Claude Code to load the change."* Do not restart it yourself, and do not claim the change is in effect before the restart: the running session still holds the old copy.
+
+Order matters: commit as soon as the edits are written, install next, restart reminder last.
+
+Project-local skills in `.claude/skills/` need no install (they load from the working copy at session start), but they still get a commit and a restart reminder.

package/skills/extra/skills/ticketing/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ticketing
+verified: 2026-10-02
+description: "MUST READ whenever the user asks to log, file, open, or create a bug, feature request, issue, or ticket (e.g. \"let's log a bug\", \"make a feature request\", \"file an issue for that\", \"ticket this\"), and before committing or opening a pull request for work that an issue tracks, so the tracker links and closes it. Default tracker is GitHub Issues on the current repo; a repo can override it (e.g. Jira) in its CLAUDE.md or AGENTS.md."
+---
+
+# Ticketing
+
+This skill owns the issue lifecycle: filing a ticket, then tying every commit and pull
+request for it back to the ticket so the tracker links the work and closes the ticket.
+
+When the user asks to log a bug or feature, create the ticket straight away. Do not ask
+where it goes, and do not ask for approval of the draft: the user wants it filed, not
+discussed.
+
+## Pick the tracker
+
+1. **Explicit in the request.** "Log it in Jira", "file it on `org/other-repo`": use that.
+2. **Repo override.** Read the current repo's `CLAUDE.md` and `AGENTS.md` for an
+   `## Issue tracking` section (format below). Use what it names.
+3. **Default: GitHub Issues on the current repo**, parsed from the `origin` remote.
+
+If none of these resolve (not in a git repo, `origin` is not on GitHub, or the named tracker
+is unreachable), stop and ask. Never fall back to a different tracker on your own.
+
+### Override format
+
+A repo that does not use GitHub Issues for its own repo declares it once:
+
+```markdown
+## Issue tracking
+
+- **Tracker:** Jira, project `ABC`
+```
+
+Other valid values:
+
+```markdown
+- **Tracker:** GitHub, repo `org/other-repo`
+- **Tracker:** Jira, project `ABC`, bug type `Defect`, feature type `Task`
+```
+
+The first files on a different GitHub repo. The second is for a Jira project whose issue
+type names differ from `Bug` / `Story`.
+
+When the user says "we use Jira for this repo" (or similar), add this section to the repo's
+`CLAUDE.md` so every later session knows.
+
+## Write the ticket
+
+Draw the content from the conversation: what broke, what was being built, what was said.
+Follow the `writing-style` skill. Ask only if there is genuinely nothing to go on.
+
+- **Title.** A plain statement of the problem or the capability, under about 70 characters.
+- **Bug body.** What happens, what should happen, steps to reproduce, and any error text
+  verbatim in a code block.
+- **Feature body.** The problem or need, then the proposed behavior.
+- **Code references.** Link files with repo-relative paths and line numbers where known.
+
+Leave out sections you have nothing for rather than filling them with placeholders.
+
+## File it on GitHub
+
+Route every `gh` call through the `github` skill's `scripts/gh-org` wrapper, so
+it runs as the account with access to the org.
+
+1. **Label.** Check which of the repo's labels exist, and use `bug` or `enhancement` only
+   if present. `gh issue create --label` fails on an unknown label; never create labels.
+
+   ```bash
+   <github-skill>/scripts/gh-org run -- gh label list --json name --jq '.[].name'
+   ```
+
+2. **Create.** Pass the body through a file so quoting cannot mangle it:
+
+   ```bash
+   <github-skill>/scripts/gh-org run -- gh issue create \
+     --title "<title>" --body-file <scratch-file> [--label bug]
+   ```
+
+   Add `--repo <org>/<repo>` (and the org before `--`) when filing somewhere other than the
+   current repo.
+
+3. **Report** the issue URL `gh` prints, and the account `gh-org` says it ran as.
+
+## File it on Jira
+
+Use the Atlassian connector (claude.ai's Atlassian MCP connector, enabled for the account).
+
+1. `createJiraIssue` with the project key from the override, issue type `Bug` for bugs and
+   `Story` for features unless the override names others.
+2. If the issue type is rejected, read the project's types with
+   `getJiraProjectIssueTypesMetadata`, pick the matching one, and add it to the override
+   so the next ticket gets it right first time.
+3. Report the issue key and its URL.
+
+## Link the work to the issue
+
+Every commit and pull request for tracked work names its issue, so the issue's timeline
+shows the work and the issue closes itself when the work lands. Never close an issue by
+hand when a commit or PR can close it.
+
+### On GitHub
+
+- **Which issue.** The one the user named, the one filed or discussed this session, or
+  `gh issue list` when the work clearly matches an open one. Unsure: ask.
+- **Partial work.** End the commit body with `Refs #N`; GitHub links the commit and leaves
+  the issue open.
+- **Finishing work.** The commit that completes the issue ends its body with `Closes #N`
+  (`Fixes #N` for a bug); GitHub closes it when the commit reaches the default branch.
+- **One line per issue.** A commit finishing two issues carries `Closes #12` and
+  `Closes #13` on separate lines; `Closes #12, #13` closes only the first.
+- **Pull requests.** Put `Closes #N` in the PR description too; the issue closes when the
+  PR merges into the default branch, and a PR into any other branch closes nothing.
+- **Another repo.** Write `org/repo#N`; a bare `#N` always means the current repo.
+- **Subject line.** Keep the reference out of it; the subject says what changed.
+- **Missed references.** Work already landed with no reference: close the issue with a
+  comment listing the commits that delivered it, short hash and subject each.
+
+### On Jira
+
+- **Key in the message.** Put the issue key, e.g. `ABC-123`, on the last line of the commit
+  body and in the PR title; the Jira GitHub integration links commits and PRs by key.
+- **Closing.** A key alone never moves the issue; transition it with
+  `transitionJiraIssue` once the work lands on the default branch.