engsys 1.0.0

package/stacks/tooling/issue-tracker-github/skills/issue-tracker-github/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: issue-tracker-github
+description: Issue tracking and project-board operations on GitHub Issues + GitHub Projects (ProjectV2). Implements the shared issue-tracker operation contract (create/list/get/update/comment/close issue; create/add-to/query board; set board field; link PR) with concrete `gh` CLI and `gh api graphql` commands. Activate when the active tracker is GitHub and the work involves filing issues, managing a project board (Phase/Priority/Owner), or linking a PR to close a work item.
+---
+
+# Issue tracker: GitHub Issues + Projects
+
+This skill is the GitHub implementation of the **shared issue-tracker operation
+contract**. Commands and agents call these operations *by name* without knowing the
+backend; the Linear pack (`issue-tracker-linear`) implements the same names so the two
+are swappable. Keep the operation names below stable.
+
+Builds on the knowledge already in the core `gh-cli` and `github-issues` skills — read
+those for full `gh` flag coverage and issue-body templates. This skill does not repeat
+them; it maps the **contract operations** onto concrete commands.
+
+**Identifiers:** GitHub issues are referenced as `#123`. Boards are GitHub ProjectV2
+("Projects"). The repo (`<owner>/<repo>`) and the Project number/owner are project facts —
+read them from `CLAUDE.md`.
+
+## Discipline: bodies come from tmp/ files, never heredocs
+
+Every operation that writes multi-line markdown (issue body, comment, PR body) writes
+the content to a `tmp/` file first and passes it with `--body-file`. Do **not** inline
+multi-line bodies via heredoc/`echo` — it mangles backticks, quotes, and `$`. One-line
+bodies may use `--body "..."`.
+
+```bash
+# Write the body, then reference it.
+#   tmp/issue-body-<slug>.md
+#   tmp/comment-<slug>.md
+#   tmp/pr-body-<slug>.md
+```
+
+## Contract operations
+
+### create-issue(title, body-from-tmp-file, type/label, [project, phase]) -> id + URL
+
+```bash
+# 1. Write the body to tmp/issue-body-<slug>.md (see github-issues for templates).
+# 2. Create. --type/--label carries the contract "type/label". Prints the issue URL.
+gh issue create \
+  --repo <owner>/<repo> \
+  --title "[Feature] <title>" \
+  --body-file tmp/issue-body-<slug>.md \
+  --label "<type-or-label>"
+# Capture the number for downstream ops:
+ISSUE_URL=$(gh issue create --repo <owner>/<repo> --title "<title>" \
+  --body-file tmp/issue-body-<slug>.md --label "<label>")
+ISSUE_NUM=$(basename "$ISSUE_URL")
+```
+
+If `[project, phase]` were supplied, follow with **add-to-board** below.
+
+### list-issues(filter: state | label/type | assignee | project/phase)
+
+```bash
+gh issue list --repo <owner>/<repo> --state open
+gh issue list --repo <owner>/<repo> --label bug
+gh issue list --repo <owner>/<repo> --assignee @me
+gh issue list --repo <owner>/<repo> --search "is:open label:bug" \
+  --json number,title,labels,assignees
+# Filter by project/phase => read the board (see query-board); Phase is a Project field,
+# not an issue field, so it is queried through the Project, not `gh issue list`.
+```
+
+### get-issue(id)
+
+```bash
+gh issue view <id> --repo <owner>/<repo> \
+  --json number,title,body,state,labels,assignees,comments
+```
+
+### update-issue(id, fields | labels | assignee)
+
+```bash
+gh issue edit <id> --repo <owner>/<repo> --title "<new title>"
+gh issue edit <id> --repo <owner>/<repo> --body-file tmp/issue-body-<slug>.md
+gh issue edit <id> --repo <owner>/<repo> --add-label ready --remove-label triage
+gh issue edit <id> --repo <owner>/<repo> --add-assignee <user>
+```
+
+### comment-issue(id, body) — records local-review findings on the work item
+
+```bash
+# Write findings to tmp/comment-<slug>.md first, then:
+gh issue comment <id> --repo <owner>/<repo> --body-file tmp/comment-<slug>.md
+```
+
+### close-issue(id)
+
+```bash
+gh issue close <id> --repo <owner>/<repo>
+gh issue close <id> --repo <owner>/<repo> --comment "Resolved by #<pr>"
+```
+
+## Boards (GitHub ProjectV2)
+
+The GitHub MCP does **not** support Projects — always use `gh project` / `gh api graphql`
+for board operations. ProjectV2 lives at the **user or org** level (not the repo), so
+board ops take `--owner <owner>` and the project **number**. Custom fields (Phase,
+Priority, Owner) are ProjectV2 fields.
+
+### create-board(name, fields: Phase, Priority, Owner)
+
+```bash
+# Create the project (board). --format json yields its number + id.
+gh project create --owner <owner> --title "<name>" --format json
+PROJECT_NUM=<number from output>
+
+# Add the three contract fields.
+#   Phase + Priority => single-select (their options are the allowed values)
+#   Owner            => single-select of usernames, or text
+gh project field-create <PROJECT_NUM> --owner <owner> \
+  --name "Phase"    --data-type SINGLE_SELECT \
+  --single-select-options "Phase 1,Phase 2,Phase 3,Phase 4"
+gh project field-create <PROJECT_NUM> --owner <owner> \
+  --name "Priority" --data-type SINGLE_SELECT \
+  --single-select-options "P0,P1,P2,P3"
+gh project field-create <PROJECT_NUM> --owner <owner> \
+  --name "Owner"    --data-type TEXT
+gh project field-list <PROJECT_NUM> --owner <owner>   # capture field ids + option ids
+```
+
+### add-to-board(issue, phase, priority, owner)
+
+```bash
+# Add the issue to the board; capture the item id it returns.
+gh project item-add <PROJECT_NUM> --owner <owner> \
+  --url https://github.com/<owner>/<repo>/issues/<issue>
+ITEM_ID=<item id from item-add --format json>
+
+# Set the three fields on that item (see set-board-field for the field/option ids).
+```
+
+### set-board-field(item, field, value)
+
+```bash
+# Single-select field (Phase, Priority): pass the option id.
+gh project item-edit --id <ITEM_ID> --project-id <PROJECT_ID> \
+  --field-id <PHASE_FIELD_ID> --single-select-option-id <PHASE_OPTION_ID>
+# Text field (Owner):
+gh project item-edit --id <ITEM_ID> --project-id <PROJECT_ID> \
+  --field-id <OWNER_FIELD_ID> --text "<owner-username>"
+```
+
+`add-to-board` = `item-add` followed by one `set-board-field` per field (Phase, Priority,
+Owner). Get the `<PROJECT_ID>`, field ids, and option ids from `field-list --format json`
+once and reuse them.
+
+### query-board(board) -> items grouped by Phase
+
+The "pick the lowest open phase" read. `gh project item-list` flattens fields; group by
+the Phase value. For full fidelity use GraphQL:
+
+```bash
+gh project item-list <PROJECT_NUM> --owner <owner> --format json \
+  --jq '.items
+        | map({num: .content.number, title: .content.title, phase: .phase, status: .status})
+        | group_by(.phase)'
+
+# GraphQL equivalent (open items, their Phase field value):
+gh api graphql -f query='
+  query($org:String!, $num:Int!){
+    organization(login:$org){
+      projectV2(number:$num){
+        items(first:100){
+          nodes{
+            content{ ... on Issue { number title state } }
+            fieldValueByName(name:"Phase"){
+              ... on ProjectV2ItemFieldSingleSelectValue { name }
+            }
+          }
+        }
+      }
+    }
+  }' -f org=<owner> -F num=<PROJECT_NUM>
+```
+
+To pick the lowest open phase: filter to open issues, take the minimum `Phase` value
+present.
+
+### close-board(board) — close the project once every issue is done
+
+Close the ProjectV2 so the board drops out of the active list — but **only when every
+issue on it is closed**. The project `item-list` `state` field is UNRELIABLE (often
+returns null/`?`), so do not trust it: intersect the board's issue numbers with the
+actually-open issues and require the intersection to be empty.
+
+```bash
+# issue numbers on the board…
+gh project item-list <PROJECT_NUM> --owner <owner> --format json --limit 400 \
+  | jq -r '.items[].content | select(.type=="Issue") | .number' | sort -u > /tmp/proj_issues.txt
+# …cross-checked against actually-open issues (NOT the board's state field)
+gh issue list --repo <owner>/<repo> --state open --limit 900 --json number --jq '.[].number' \
+  | sort -u > /tmp/open_issues.txt
+comm -12 /tmp/proj_issues.txt /tmp/open_issues.txt   # ← MUST be empty before closing
+
+# if the intersection is empty:
+gh project close <PROJECT_NUM> --owner <owner>
+```
+
+- **Gate:** any issue still open → do NOT close (the project isn't done; stop and
+  report). Draft cards / notes (non-issue items) do **not** gate — only real issues do.
+- Reversible: `gh project close <PROJECT_NUM> --owner <owner> --undo` reopens it.
+  Closing archives the board from the active view; it does not delete the project or its
+  items.
+
+## link-pr(issue, pr) — how a merged PR closes/links the work item
+
+GitHub auto-closes linked issues when a PR merges if the PR body contains a closing
+keyword. **One keyword per line — never comma-separated** (GitHub closes only the first
+issue on a comma-separated line).
+
+```bash
+# Write the PR body to tmp/pr-body-<slug>.md with one closing keyword per line:
+#   Closes #<issue>
+#   Closes #<other-issue>
+gh pr create --repo <owner>/<repo> --title "<title>" \
+  --body-file tmp/pr-body-<slug>.md
+```
+
+On merge, GitHub closes each referenced issue and records the PR link on it. PRs and CI
+stay on GitHub (`gh`).
+
+## Hard-won lessons
+
+GitHub Issues/Projects API gotchas that fail silently or destructively. Each is
+Symptom / Cause / Fix.
+
+### Verify a label exists before filing an issue with it
+
+- **Symptom:** `gh issue create --label X` errors with `could not add label: 'X' not found`
+  and the issue is **not** created — no partial success. Batch issue-filing runs waste every
+  `gh` call when an assumed label (`dashboard`, `recommendation-engine`) isn't the repo's
+  actual label (`frontend`, `recommendation`).
+- **Cause:** `gh` rejects the whole create when any `--label` doesn't exist in the repo.
+- **Fix:** List labels first and map your intent → real names before filing:
+  ```bash
+  gh label list --repo <owner>/<repo> --limit 100 --json name --jq '.[].name' | sort
+  ```
+  Don't trust cached label lists from prior runs — query the live list each time.
+
+### ProjectV2 single-select fields are GraphQL-only
+
+- **Symptom:** A fresh `gh project create` board has only built-in fields (`Title`,
+  `Assignees`, `Status`, `Labels`, …). There's no `gh` shortcut to add a single-select field
+  with options (Phase / Priority / Owner), so operators end up configuring them by hand in the
+  UI for every issue.
+- **Cause:** The `gh` CLI has no subcommand to create or edit a single-select field's option
+  list — `field-create` makes a field, `field-delete` removes one, `item-edit` sets a value on
+  an item; none append/rename options on an existing single-select field.
+- **Fix:** Create and edit single-select fields with `gh api graphql` (`createProjectV2Field`
+  with `dataType: SINGLE_SELECT` and `singleSelectOptions`). Verify with
+  `gh project field-list <num> --owner <owner>` before assuming `Status` is the only field.
+
+### updateProjectV2Field preserves option IDs verbatim — pass the full set
+
+- **Symptom:** Adding one new option to an existing single-select field (e.g. a new Phase)
+  silently orphans **every** previously-categorized item to "(no phase)" — the value vanishes
+  from each item even though the field still exists. Observed: 21 items lost their Phase on one
+  add.
+- **Cause:** `updateProjectV2Field` treats `singleSelectOptions` as the **authoritative state**,
+  not a delta. Omitting existing options regenerates all option IDs, orphaning every board item
+  that referenced an old ID.
+- **Fix:** First fetch the existing options + IDs, then call `updateProjectV2Field` with the
+  **full** array — every existing option's `id` reused verbatim plus the new one appended.
+  Afterward audit immediately and re-set any orphans:
+  ```bash
+  gh project item-list <num> --owner <owner> --format json \
+    | jq '[.items[] | select(.phase == null)] | length'   # must be 0
+  ```
+
+## See also
+
+- core `gh-cli` — full `gh` command/flag reference.
+- core `github-issues` — issue-body templates, labels, MCP fallback.
+- core `github-actions` — workflow expression/injection/draft-gate/rate-limit lessons.

package/stacks/tooling/issue-tracker-linear/claude.fragment.md

@@ -0,0 +1,17 @@
+## Issue tracking
+
+- **Active tracker: Linear.** Agents use the `issue-tracker-linear` skill for all issue
+  and board operations (via the Linear MCP): create/list/get/update/comment/close issue;
+  create/add-to/query board; set board field; link PR.
+- PRs and CI stay on GitHub via `gh`; Linear auto-links them through its GitHub
+  integration (magic words like `Fixes ABC-123` in the PR title/description, or a branch
+  named `<team>-<n>-slug`).
+- The board maps to a Linear **Project**; **Phase**→milestone, **Priority**→native issue
+  priority, **Owner**→assignee.
+
+The Linear MCP connector (`https://mcp.linear.app/mcp`, configured in this pack's
+`settings.fragment.json`) must be enabled and authorized in the session for the skill to
+reach Linear.
+
+<!-- naturalize: set the Linear team key (e.g. ABC) and the project that holds the board.
+team-key: <TEAM_KEY> -->

package/stacks/tooling/issue-tracker-linear/settings.fragment.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {},
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}

package/stacks/tooling/issue-tracker-linear/skills/issue-tracker-linear/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: issue-tracker-linear
+description: Issue tracking and project-board operations on Linear, via the Linear MCP. Implements the shared issue-tracker operation contract (create/list/get/update/comment/close issue; create/add-to/query board; set board field; link PR) mapped onto Linear issues, projects, milestones, priorities, and assignees. Activate when the active tracker is Linear and the work involves filing issues, managing a Linear project/board (Phase/Priority/Owner), or linking a PR to close a work item.
+---
+
+# Issue tracker: Linear
+
+This skill is the Linear implementation of the **shared issue-tracker operation
+contract**. Commands and agents call these operations *by name* without knowing the
+backend; the GitHub pack (`issue-tracker-github`) implements the same names, so the two
+are swappable. Keep the operation names below stable.
+
+Linear is reached through the **Linear MCP** (tools prefixed `mcp__claude_ai_Linear__`).
+There is no Linear CLI — every operation is an MCP tool call, so this pack adds no Bash
+permissions. If the tools are not visible in the session, discover them via tool search;
+the MCP connector must be enabled (see the pack's `claude.fragment.md`).
+
+**Note — no separate create tool:** `save_issue`, `save_project`, and `save_milestone`
+each do **both create and update** (omit the id to create, pass it to update).
+
+## Project facts (naturalize)
+
+The Linear **team** and **project** are project facts. Read the **team key** (e.g.
+`ABC`) from `CLAUDE.md`. Resolve the team/project to their ids once via `list_teams` /
+`list_projects` and reuse them.
+
+### Identifier mapping
+
+| Backend | Issue id form        |
+| ------- | -------------------- |
+| GitHub  | `#123`               |
+| Linear  | `ABC-123` (team-prefixed) |
+
+Callers may pass either the human identifier (`ABC-123`) or the issue's internal id;
+`get_issue` / `save_issue` accept the identifier.
+
+## Contract -> Linear mapping (board fields)
+
+A contract "board" is a **Linear Project**. The board's three custom fields map onto
+native Linear concepts — there are no ad-hoc custom fields:
+
+| Contract field | Linear concept                        | Tool to set it                          |
+| -------------- | ------------------------------------- | --------------------------------------- |
+| Board          | **Project**                           | `save_project`                          |
+| Phase          | **Milestone** (project milestone)     | `save_milestone` + `save_issue` (milestone) |
+| Priority       | **Issue priority** (native, 0–4)      | `save_issue` (priority)                 |
+| Owner          | **Assignee**                          | `save_issue` (assignee)                 |
+| State/Status   | **Workflow state** (Todo/Done/…)      | `save_issue` (state via `list_issue_statuses`) |
+
+(Phase may alternatively map to a **label set** instead of milestones; prefer milestones
+— they are ordered, which makes "lowest open phase" a natural sort.)
+
+## Contract operations
+
+### create-issue(title, body-from-tmp-file, type/label, [project, phase]) -> id + URL
+
+`save_issue` with no id creates. Set `team` (the team key), `title`, `description`
+(the body), `labels` (the contract type/label), and optionally `assignee`, `project`,
+`priority`. Read the long markdown body from `tmp/issue-body-<slug>.md` and pass its
+contents as `description` (real newlines, not `\n`).
+
+```text
+save_issue(team: "ABC", title: "<title>", description: <contents of tmp/issue-body-<slug>.md>,
+           labels: ["<type-or-label>"], assignee: <owner?>, project: <project?>)
+-> returns the issue identifier (ABC-123) and URL.
+```
+
+If `[project, phase]` were supplied, follow with **add-to-board**.
+
+### list-issues(filter: state | label/type | assignee | project/phase)
+
+`list_issues` with the matching filter (filter by `team`, `project`, `state`/status,
+`assignee`, `label`, or `cycle`). For a project/phase filter, list by `project` and
+read each issue's milestone (see query-board).
+
+### get-issue(id)
+
+`get_issue(id: "ABC-123")` -> full issue (title, description, state, labels, assignee,
+priority, project, milestone).
+
+### update-issue(id, fields | labels | assignee)
+
+`save_issue` **with the id** updates only the passed fields:
+
+```text
+save_issue(id: "ABC-123", title?: ..., description?: ..., labels?: [...], assignee?: ...)
+```
+
+### comment-issue(id, body) — records local-review findings on the work item
+
+`save_comment(issueId: "ABC-123", body: <contents of tmp/comment-<slug>.md>)`.
+
+### close-issue(id)
+
+Linear has no "close" verb — set the issue to a **Done** (or **Canceled**) workflow
+state. Resolve the state id once via `list_issue_statuses(team: "ABC")`, then:
+
+```text
+save_issue(id: "ABC-123", state: "Done")   # or "Canceled"
+```
+
+## Boards (Linear Projects + Milestones)
+
+### create-board(name, fields: Phase, Priority, Owner)
+
+`save_project(name: "<name>", teamId: <team>)` creates the project (board). Then create
+one **milestone per Phase** (these are the Phase field's values):
+
+```text
+save_project(name: "<name>", teams: ["ABC"])         -> project id
+save_milestone(projectId: <project>, name: "Phase 1")
+save_milestone(projectId: <project>, name: "Phase 2")
+save_milestone(projectId: <project>, name: "Phase 3")
+```
+
+Priority and Owner need no setup — they are native issue fields (priority, assignee).
+
+### add-to-board(issue, phase, priority, owner)
+
+One `save_issue` setting all four:
+
+```text
+save_issue(id: "ABC-123",
+           project:  <project>,
+           milestone: <milestone for "phase">,   # Phase
+           priority:  <0–4>,                      # Priority (1=Urgent … 4=Low, 0=None)
+           assignee:  "<owner>")                  # Owner
+```
+
+Resolve the milestone for a phase via `list_milestones(projectId: <project>)`.
+
+### set-board-field(item, field, value)
+
+All board fields are issue fields, so this is `save_issue` with the one field:
+
+```text
+save_issue(id: "ABC-123", milestone: <…>)   # Phase
+save_issue(id: "ABC-123", priority: <0–4>)  # Priority
+save_issue(id: "ABC-123", assignee: <…>)    # Owner
+```
+
+### query-board(board) -> items grouped by Phase
+
+`list_issues(project: <project>)`, then group the results by each issue's **milestone**
+(Phase). To "pick the lowest open phase": filter to non-Done issues, group by milestone,
+and take the earliest milestone (milestones are ordered) that still has open issues.
+Use `list_milestones(projectId: <project>)` for the canonical phase order.
+
+### close-board(board) — close the project once every issue is done
+
+Mark the Linear **project** Completed so it drops off the active board — but **only when
+every issue in it is Done or Canceled**. Check with `list_issues(project: <project>)` and
+confirm none remain in a non-terminal state (use `list_issue_statuses(team: "ABC")` to
+know which states are terminal); the count of non-terminal issues must be zero.
+
+```
+save_project(id: <project>, state: "completed")   # Linear project status → Completed
+```
+
+- **Gate:** any issue still open / in progress → do NOT complete the project (it isn't
+  done; stop and report).
+- Reversible: re-open by setting the project state back (e.g. `"started"`). Completing
+  drops it from the active view; it does not delete the project or its issues.
+
+## link-pr(issue, pr) — how a merged PR closes/links the work item
+
+PRs and CI stay on **GitHub** (`gh`). Linear's GitHub integration auto-links and
+auto-closes the issue via **magic words**, no MCP call needed:
+
+- Branch named `<team>-<n>-slug` (e.g. `abc-123-fix-login`) — Linear links it
+  automatically, and
+- a closing magic word in the **PR title or description**: `Fixes ABC-123`,
+  `Closes ABC-123`, `Resolves ABC-123`.
+
+When the PR merges, Linear moves `ABC-123` to its Done state and records the PR link.
+So `link-pr` is realized by naming the branch / writing the magic word when the PR is
+created via `gh` — there is no separate Linear tool call.
+
+## See also
+
+- The GitHub pack `issue-tracker-github` implements the same contract on GitHub Issues +
+  Projects — same operation names, swappable backend.
+- core `gh-cli` — PR creation (`gh pr create`) still goes through GitHub.