engsys 1.0.0

package/core/skills/git-workflow-agents/reference.md

@@ -0,0 +1,220 @@
+# Git Workflow for Agents - Reference
+
+This is auxiliary, stack-agnostic reference material for the worktree workflow. The authoritative
+guidance is [SKILL.md](SKILL.md). Commands here use placeholders like `<install-deps-command>`,
+`<build-command>`, `<test-command>`, and `<project>` — substitute your project's actual tooling.
+Examples are shown in bash; translate to your shell as needed.
+
+## Helper Script Sketch
+
+A `create-worktree` helper takes an issue number and slug, then:
+
+```bash
+# Usage: create-worktree <issue-number> <slug>
+ISSUE="$1"; SLUG="$2"
+BRANCH="agent/${ISSUE}-${SLUG}"
+WORKTREE="../worktrees/issue-${ISSUE}-${SLUG}"
+
+cd <repo-root>
+git fetch origin
+git checkout main
+git pull origin main
+
+# Create worktree AND branch together
+git worktree add "$WORKTREE" -b "$BRANCH"
+
+cd "$WORKTREE"
+[ -f ../../<project>/.env.local ] && cp ../../<project>/.env.local .env.local
+<install-deps-command>
+echo "Worktree ready at $WORKTREE on branch $BRANCH"
+```
+
+A `cleanup-worktrees` helper lists worktrees, empties each directory (so removal does not fail with
+"Directory not empty" — git won't delete non-git files like dependency dirs or build output), then
+removes them and prunes stale references and merged `agent/` branches:
+
+```bash
+cd <repo-root>
+git worktree list
+# For each non-primary worktree: empty its dir, then `git worktree remove <path> --force`
+git worktree prune
+git branch --merged main | grep 'agent/' | xargs -r git branch -d
+```
+
+## Single vs. Multi-Package Workflows
+
+For a single package/module, install and build just that target. For a monorepo touching several
+packages, install all workspaces and use the package manager's filter/scope mechanism to build only
+the affected packages plus their dependents. The principle is the same regardless of language:
+**build the changed package and everything that depends on it.**
+
+## Database / Schema Migration Strategies
+
+When a change includes a schema or data-layer migration, coordinate so parallel agents don't
+corrupt a shared database.
+
+- **Strategy 1 — Coordination (recommended for dev):** one agent creates and commits the migration;
+  others rebase on `origin/main` and apply pending migrations to their local DB before continuing.
+- **Strategy 2 — Separate databases per worktree:** override the DB connection string in each
+  worktree's `.env.local`, create a uniquely-named database per worktree, and run migrations there.
+- **Strategy 3 — Isolated dev database:** point each worktree at its own remote dev database.
+
+After a migration lands, regenerate any generated client/codegen artifacts and rebuild dependent
+packages.
+
+## Infrastructure Validation
+
+If the project uses infrastructure-as-code, validate locally before committing using the project's
+IaC tool (Terraform `plan`/`validate`, Bicep `build` + deployment `what-if`/`validate`,
+CloudFormation `validate-template`, Pulumi `preview`, etc.). Preview the diff against the target
+environment before deploying. Never make changes through a cloud console that bypass the IaC.
+
+## Troubleshooting
+
+### Worktree creation fails
+
+`fatal: '<branch>' is already checked out at '<path>'` — the branch is checked out elsewhere.
+
+```bash
+git worktree list                 # find where it's checked out
+git worktree remove <path>        # remove if stale
+# or pick a new branch name
+git worktree add ../worktrees/issue-42-foo-v2 -b agent/42-foo-v2
+```
+
+### Worktree won't remove
+
+`contains modified or untracked files` — commit/stash first, or force:
+
+```bash
+git worktree remove --force <worktree-path>
+```
+
+`Directory not empty` — git does not delete non-git files (dependency dirs, build output). Empty the
+directory first, then remove:
+
+```bash
+rm -rf ../worktrees/issue-42-foo/*
+git worktree remove ../worktrees/issue-42-foo
+```
+
+### Build fails after switching worktrees
+
+Stale dependencies are the usual cause. Clean and reinstall:
+
+```bash
+rm -rf <deps-dir> <lockfile>
+<install-deps-command>
+<build-command>
+```
+
+### Tests fail with database errors
+
+Point tests at a dedicated test database (separate connection string in `.env.local`/`.env.test`),
+reset/seed it, and isolate the test DB per worktree if agents run in parallel.
+
+### Merge conflicts during rebase
+
+```bash
+git fetch origin main
+git rebase origin/main
+# resolve conflicts, then:
+git add <resolved-files>
+git rebase --continue
+# if it gets messy:
+git rebase --abort
+```
+
+If the rebase stops on a commit already merged to main (expected for stacked branches):
+
+```bash
+git rebase --skip
+```
+
+After a successful rebase, force-push safely:
+
+```bash
+git push --force-with-lease origin agent/<branch>
+```
+
+### Disk-space pressure from many worktrees
+
+Prefer a package manager that hard-links/dedupes dependencies, install only the workspaces you need,
+and clean build artifacts and removed worktrees aggressively (`git worktree prune`).
+
+## Advanced Workflows
+
+### Cleaning up commit history
+
+```bash
+git rebase -i origin/main         # squash/reword/drop commits
+git push --force-with-lease       # only if the branch isn't shared
+```
+
+### Cherry-picking / sharing work between worktrees
+
+```bash
+# In source worktree: find the commit
+git log --oneline
+# In target worktree: apply it
+git cherry-pick <commit-hash>
+```
+
+Sharing via committed-and-pushed commits (then `git fetch` + cherry-pick) is safer than copying
+working-tree files.
+
+### Switching issues mid-work
+
+Commit WIP (`wip: save progress (#42)`), optionally push to preserve it, create/switch to the other
+issue's worktree, and return later by `cd`-ing back.
+
+## GitHub via gh CLI (preferred) and MCP (fallback)
+
+Prefer `gh` CLI for issues, PRs, Actions, and project boards. Examples:
+
+```bash
+gh issue create --repo <owner>/<repo> --title "..." --body-file tmp/issue-body.md --label "bug"
+gh issue view 42 --repo <owner>/<repo>
+gh pr create --base main --head agent/42-foo --title "fix(scope): ..." --body-file tmp/pr-body-42.md
+```
+
+The `github` MCP server (configured in `.mcp.json`) is a fallback for when `gh` auth or network
+fails. ProjectV2 (project boards) must always use `gh project` / `gh api graphql` — MCP does not
+support them.
+
+## Git Worktree Command Reference
+
+```bash
+git worktree list                         # list
+git worktree list --porcelain             # machine-readable
+git worktree add <path> -b <branch>       # new branch + worktree (preferred)
+git worktree add <path> <branch>          # existing branch (if not checked out elsewhere)
+git worktree add <path> -b <branch> <sha> # from a specific commit
+git worktree remove <path>                # remove
+git worktree remove --force <path>        # ignore uncommitted changes
+git worktree prune                        # drop stale references
+git worktree prune --dry-run              # preview
+```
+
+To "move" a worktree: note its branch, `git worktree remove` the old path, then `git worktree add`
+at the new path.
+
+## Diffing your branch against main
+
+```bash
+git diff main...HEAD              # changes in your branch only (merge-base)
+git diff main..HEAD              # all differences between the two tips
+git diff --name-only main...HEAD # file names only
+git diff --stat main...HEAD      # summary stats
+```
+
+## FAQ
+
+- **Multiple worktrees for one issue?** No — one issue, one worktree. Use commits to checkpoint and
+  share progress.
+- **Committed in the main checkout by mistake?** Note the hash, `git reset --hard origin/main` in the
+  main checkout, then `git cherry-pick <hash>` in the worktree.
+- **Run the same service in two worktrees at once?** Yes, but assign different ports (e.g. via a
+  `PORT` env var) to avoid collisions.
+- **Worktrees for small fixes?** Only when isolation/parallelism justifies the setup overhead;
+  otherwise a plain branch in the main checkout is fine.

package/core/skills/github-actions/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: github-actions
+description: GitHub Actions workflow authoring guidance — the `${{ }}` expression function set, shell-injection and multi-line-output safety in `run:` steps, draft-gated CI triggers, and GraphQL rate-limit handling. Activate when editing `.github/workflows/*.yml`/`*.yaml`, authoring or reviewing GitHub Actions workflows, or debugging a CI gate that runs/skips unexpectedly.
+---
+
+# GitHub Actions
+
+Practical, hard-won guidance for authoring and reviewing GitHub Actions workflows.
+GitHub is the assumed code host for every project here — PRs and CI live on GitHub — so
+this skill is installed everywhere. It complements core `gh-cli` (which covers `gh run`,
+`gh workflow`, `gh secret` from the command line); this skill is about the workflow YAML
+itself.
+
+Each lesson below is something that **looks right but is silently wrong**: it passes
+review, ships, and then fails open (a gate never runs, a value truncates, an injection
+lands). Apply the review checklist at the bottom to any workflow PR.
+
+## 1. The `${{ }}` expression language has a tiny function set
+
+GitHub Actions expressions are **not JavaScript**. The only built-in functions are:
+
+```text
+contains  startsWith  endsWith  format  join  toJSON  fromJSON  hashFiles
+```
+
+There is **no** `toLower`, `toUpper`, `trim`, or `replace`. Typing one does not error —
+the expression evaluates to an empty string **silently**, so a condition that was meant
+to exclude something fails open and never excludes it.
+
+```yaml
+# ❌ WRONG — toLower() does not exist; the whole expression is "" and the guard never fires
+if: ${{ !contains(toLower(github.event.pull_request.title), 'release') }}
+```
+
+Workaround A — enumerate the case variants with the functions that do exist:
+
+```yaml
+# ✅ Cover the common cases explicitly
+if: |
+  !startsWith(github.event.pull_request.title, 'Release') &&
+  !startsWith(github.event.pull_request.title, 'release') &&
+  !startsWith(github.event.pull_request.title, 'RELEASE')
+```
+
+Workaround B — do the string munging in a `run:` step (shell has real `tr`, `sed`, etc.)
+and emit a normalized value as a step output, then branch on that:
+
+```yaml
+- id: norm
+  env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: |
+    lower="$(printf '%s' "$TITLE" | tr '[:upper:]' '[:lower:]')"
+    echo "is_release=$(case "$lower" in release*) echo true;; *) echo false;; esac)" >> "$GITHUB_OUTPUT"
+- if: steps.norm.outputs.is_release == 'false'
+  run: ...
+```
+
+Reference: <https://docs.github.com/en/actions/learn-github-actions/expressions#functions>.
+Any `toLower`/`toUpper`/`trim`/`replace` inside `${{ }}` is a bug — rewrite it.
+
+## 2. `run:` step safety — outputs and injection
+
+### Multi-line step outputs need a heredoc delimiter
+
+Writing `echo "result=$value" >> "$GITHUB_OUTPUT"` captures only the **first line** when
+`$value` is multi-line (e.g. a failed `gh api` JSON body, a `git log`/`git diff`
+aggregation, anything piped through `jq`/`yq` without `-r .field`). Downstream steps then
+branch on a truncated, present-but-stale string — silent state corruption.
+
+```yaml
+# ❌ WRONG — truncates at the first newline
+- id: convert
+  run: |
+    output="$(gh api graphql ... 2>&1)"
+    echo "result=$output" >> "$GITHUB_OUTPUT"
+
+# ✅ CORRECT — heredoc delimiter; runner reads until the closing EOF
+- id: convert
+  run: |
+    output="$(gh api graphql ... 2>&1)"
+    {
+      echo "result<<EOF"
+      echo "$output"
+      echo "EOF"
+    } >> "$GITHUB_OUTPUT"
+```
+
+The delimiter (`EOF`, or any unique string not present in the payload) tells the runner
+to read to the matching closer instead of splitting on `\n`. When in doubt, use it — the
+cost is two lines, the bug is invisible.
+
+### Never inline-expand `${{ github.* }}` inside a `run:` body
+
+`${{ ... }}` is **textually substituted before the shell parses the line**. If the value
+contains shell metacharacters — quotes, backticks, `$(...)`, `;` — the shell executes
+them. With attacker-influenced inputs (PR title, `head_ref`, branch name, issue body,
+fork commit messages) this is direct command injection.
+
+```yaml
+# ❌ WRONG — injection surface; substituted before the shell parses it
+- run: |
+    gh api graphql -F id='${{ github.event.pull_request.node_id }}' -f query='...'
+
+# ✅ CORRECT — pass via env:, dereference the (quoted) env var
+- env:
+    PR_NODE_ID: ${{ github.event.pull_request.node_id }}
+  run: |
+    gh api graphql -F id="$PR_NODE_ID" -f query='...'
+```
+
+Rule of thumb: **`${{ ... }}` belongs in `with:`, `env:`, `if:`, and `name:` — not in
+`run:` script bodies.** The bar is not "is this field safe today?" but "will the pattern
+still be safe when someone copies it and substitutes the PR title?" Genuinely safe
+exceptions: `${{ secrets.* }}` in an `env:` mapping, and `${{ runner.os }}` / `${{ matrix.* }}`
+defined entirely by the workflow itself. For user-influenced data there are no exceptions.
+
+(Optional but cheap: `pipx install zizmor && zizmor .github/workflows` flags the
+`template-injection` category automatically.)
+
+## 3. Draft-gated jobs need `ready_for_review` in the trigger
+
+A job guarded by `if: github.event.pull_request.draft == false` only runs on events the
+workflow is actually subscribed to. A `pull_request:` trigger with no `types:` key
+defaults to `[opened, synchronize, reopened]` — which does **not** include
+`ready_for_review`.
+
+Consequence: you mark the PR Ready expecting the required gate to run, but no new run is
+scheduled. The gated leg stays `SKIPPED` from the last draft run, and GitHub treats a
+SKIPPED required check as satisfied — so the PR shows mergeable as a **hollow green**.
+
+```yaml
+# ❌ Marking Ready never schedules a run — ready_for_review isn't subscribed
+on:
+  pull_request:
+    branches: [main]
+
+# ✅ The draft→ready transition itself fires the workflow
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main]
+```
+
+Add `synchronize` too (it's in the default set, but list it explicitly once you specify
+`types:`, since specifying `types:` replaces the default entirely). Until the trigger is
+fixed, the manual workaround is to force a `synchronize` event:
+
+```bash
+git commit --allow-empty -m "chore: trigger CI after ready-for-review" && git push
+gh pr checks <pr-number> --watch   # confirm the gated leg shows COMPLETED/SUCCESS, not SKIPPED
+```
+
+Before merging a draft-gated PR: confirm `mergeStateStatus == CLEAN` (not merely
+`MERGEABLE`), the specific leg shows COMPLETED/SUCCESS, and that run was triggered **after**
+the PR was marked Ready.
+
+## 4. GraphQL / API rate limits — defer, don't block the run
+
+`gh api graphql`, `gh project item-edit`, and `gh issue edit --add-assignee` consume the
+**per-user** GraphQL budget (5,000/hr), shared across every tool and agent on that token.
+A burst of parallel mutations drains it in minutes; the error is
+`API rate limit already exceeded for user ID …`.
+
+- **Don't block the whole run on it.** Capture the GraphQL-dependent work (assign issues,
+  flip board status) and continue with everything that doesn't need GraphQL. Most REST
+  calls (`gh issue view`, `gh pr create`, `gh api repos/...`) draw on the separate `core`
+  budget. Retry the deferred work after the `reset` timestamp passes (~15 min).
+- **Mutate sequentially, not in parallel.** A tight `for` loop (one mutation per item)
+  is gentler than bursty parallel calls, which compound the problem.
+- Peek before a long sequence of board mutations; below ~200 remaining, defer:
+
+```bash
+gh api rate_limit --jq '.resources'   # compare .graphql.remaining vs .core.remaining
+```
+
+## Review checklist (any workflow PR)
+
+```text
+[ ] No toLower/toUpper/trim/replace inside ${{ }} — only contains/startsWith/endsWith/
+    format/join/toJSON/fromJSON/hashFiles exist; munge strings in a run: step instead.
+[ ] Every `>> $GITHUB_OUTPUT` for a possibly-multi-line value uses the heredoc
+    delimiter form (or the value is guaranteed single-line via `-r .field`/`head -n1`).
+[ ] No ${{ github.* }} / ${{ steps.* }} / ${{ inputs.* }} inline-expanded inside a
+    run: body — pass via env: and dereference the quoted env var.
+[ ] Any draft-gated required job: `ready_for_review` (and `synchronize`) is in the
+    pull_request: types: list, so marking Ready actually schedules the gate.
+[ ] GraphQL-heavy steps tolerate a rate limit (defer, don't fail the run) and mutate
+    sequentially rather than in parallel.
+```

package/core/skills/github-issues/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: github-issues
+description: 'Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task.'
+---
+
+# GitHub Issues
+
+Manage GitHub issues using `gh` CLI (preferred) with `user-github` MCP server as fallback.
+
+**Important:** The GitHub MCP does **not** support GitHub Projects (ProjectV2). For project board operations (priorities, status, custom fields, waves), always use `gh project` or `gh api graphql`.
+
+## Tool Priority
+
+1. **`gh` CLI** (preferred) — full coverage, projects support, GraphQL access
+2. **GitHub MCP** (fallback) — use when `gh` CLI has auth or connectivity issues
+
+## Available MCP Tools (fallback only)
+
+| Tool                             | Purpose                |
+| -------------------------------- | ---------------------- |
+| `mcp__github__create_issue`      | Create new issues      |
+| `mcp__github__update_issue`      | Update existing issues |
+| `mcp__github__get_issue`         | Fetch issue details    |
+| `mcp__github__search_issues`     | Search issues          |
+| `mcp__github__add_issue_comment` | Add comments           |
+| `mcp__github__list_issues`       | List repository issues |
+
+## Workflow
+
+1. **Determine action**: Create, update, or query?
+2. **Gather context**: Get repo info, existing labels, milestones if needed
+3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md)
+4. **Execute**: Use `gh` CLI first; fall back to MCP tools if CLI has issues
+5. **Confirm**: Report the issue URL to user
+
+## Creating Issues
+
+### Using gh CLI (preferred)
+
+```bash
+# Write body to tmp/ file first, then:
+gh issue create \
+  --repo <owner>/<repo> \
+  --title "🐛 Bug: Description" \
+  --body-file tmp/issue-body-slug.md \
+  --label "bug,<component>"
+```
+
+### Using MCP (fallback)
+
+### Required Parameters
+
+```text
+owner: repository owner (org or user)
+repo: repository name
+title: clear, actionable title
+body: structured markdown content
+```
+
+### Optional Parameters
+
+```text
+labels: ["bug", "enhancement", "documentation", ...]
+assignees: ["username1", "username2"]
+milestone: milestone number (integer)
+```
+
+### Title Guidelines
+
+- Start with type prefix when useful: `[Bug]`, `[Feature]`, `[Docs]`
+- Be specific and actionable
+- Keep under 72 characters
+- Examples:
+  - `[Bug] Login fails with SSO enabled`
+  - `[Feature] Add dark mode support`
+  - `Add unit tests for auth module`
+
+### Body Structure
+
+Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type:
+
+| User Request                    | Template        |
+| ------------------------------- | --------------- |
+| Bug, error, broken, not working | Bug Report      |
+| Feature, enhancement, add, new  | Feature Request |
+| Task, chore, refactor, update   | Task            |
+
+## Updating Issues
+
+Use `mcp__github__update_issue` with:
+
+```text
+owner, repo, issue_number (required)
+title, body, state, labels, assignees, milestone (optional - only changed fields)
+```
+
+State values: `open`, `closed`
+
+## Examples
+
+### Example 1: Bug Report
+
+**User**: "Create a bug issue - the login page crashes when using SSO"
+
+**Action**: Call `mcp__github__create_issue` with:
+
+```json
+{
+  "owner": "github",
+  "repo": "awesome-copilot",
+  "title": "[Bug] Login page crashes when using SSO",
+  "body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.",
+  "labels": ["bug"]
+}
+```
+
+### Example 2: Feature Request
+
+**User**: "Create a feature request for dark mode with high priority"
+
+**Action**: Call `mcp__github__create_issue` with:
+
+```json
+{
+  "owner": "github",
+  "repo": "awesome-copilot",
+  "title": "[Feature] Add dark mode support",
+  "body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.",
+  "labels": ["enhancement", "high-priority"]
+}
+```
+
+## Common Labels
+
+Use these standard labels when applicable:
+
+| Label              | Use For                       |
+| ------------------ | ----------------------------- |
+| `bug`              | Something isn't working       |
+| `enhancement`      | New feature or improvement    |
+| `documentation`    | Documentation updates         |
+| `good first issue` | Good for newcomers            |
+| `help wanted`      | Extra attention needed        |
+| `question`         | Further information requested |
+| `wontfix`          | Will not be addressed         |
+| `duplicate`        | Already exists                |
+| `high-priority`    | Urgent issues                 |
+
+## Tips
+
+- Always confirm the repository context before creating issues
+- Ask for missing critical information rather than guessing
+- Link related issues when known: `Related to #123`
+- For updates, fetch current issue first to preserve unchanged fields