@lovehlmmm/primekit 1.0.0

package/skills/github/references/issue-workflows.md

@@ -0,0 +1,151 @@
+# Issue Workflows
+
+Playbooks for creating, updating, and closing issues with `gh`. Every claim in
+an issue must carry evidence (`file:line`, command output, commit SHA, run
+URL). Author prose in the resolved writing language.
+
+## Create an issue
+
+### 1. Scout first (mandatory)
+
+Activate `pk:scout` on the area the issue concerns. Collect: owning files,
+relevant functions, existing behavior, and nearby tests. An issue written
+without codebase grounding is not created — the scout output is its evidence
+base.
+
+### 2. Dedup + already-resolved check (mandatory)
+
+Never create a duplicate, and never file a bug that is already fixed:
+
+```bash
+# Open AND closed issues — closed catches "already resolved"
+gh issue list --state all --search "<keywords>" --limit 20 \
+  --json number,title,state,closedAt,url
+gh search issues "<keywords> repo:<owner>/<repo>" --limit 10
+# PRs may have fixed it without an issue
+gh pr list --state merged --search "<keywords>" --limit 10 --json number,title,url
+```
+
+Then check git history and other branches — a fix may exist unmerged:
+
+```bash
+git log --all --oneline --grep "<keywords>" -20
+git log --all -S "<code fragment>" --oneline -10   # pickaxe: when the code changed
+git branch -r --contains <sha>                      # which branches carry the fix
+```
+
+Outcomes:
+- **Duplicate open issue** → comment on it with your new evidence instead of
+  creating a new one; report the existing URL.
+- **Already resolved** (closed issue / merged PR / fix on a branch) → do not
+  create; report where it was resolved, and whether the fix has shipped to the
+  default branch.
+- **Genuinely new** → proceed.
+
+### 3. Labels
+
+Keep the label set consistent. Inspect before use; create missing standard
+labels rather than inventing near-duplicates:
+
+```bash
+gh label list --limit 100 --json name -q '.[].name' > /tmp/labels.txt
+grep -qxF "bug" /tmp/labels.txt \
+  || gh label create "bug" --color d73a4a --description "Something isn't working"
+```
+
+Guard with an explicit existence check instead of `2>/dev/null || true` —
+the latter swallows permission and network errors alongside the intended
+"already exists" case.
+
+Standard taxonomy (create on demand, reuse existing spellings when the repo
+already has equivalents — never create `enhancement` next to `enhance`):
+
+| Label | Use for |
+|-------|---------|
+| `bug` | Incorrect behavior with reproduction evidence |
+| `feature` | New capability |
+| `enhancement` | Improvement to existing behavior |
+| `docs` | Documentation only |
+| `security` | Vulnerability or hardening (never include exploit secrets) |
+| `ci` | Pipeline/workflow issues |
+| `refactor` | Internal restructuring, no behavior change |
+| `question` | Needs clarification/decision |
+| `priority:high/medium/low` | Triage priority |
+
+Apply 1 type label + optional priority. In `--interactive`, confirm new label
+creation with the user.
+
+### 4. Structure the body
+
+Use `assets/templates/issue-*.md` (repo's own `.github/ISSUE_TEMPLATE/` wins
+when present). Requirements for every issue body:
+
+- **Short summary first** — one paragraph a reader understands immediately.
+- **Flow description** — how the behavior works today vs expected, with
+  `file:line` anchors.
+- **Diagram when flow is non-trivial** — a small Mermaid block
+  (`flowchart` or `sequenceDiagram`) beats three paragraphs. Skip diagrams
+  for one-step issues.
+- **Conditions / constraints** — versions, platforms, config required.
+- **Open questions** — explicit list of decisions needed from maintainers.
+- **Notes** — pitfalls, related issues/PRs (link them), affected branches.
+- Concise. Cut every sentence that adds no decision-relevant information.
+
+### 5. Create
+
+```bash
+gh issue create --title "<type>: <concise title>" \
+  --body-file <tmpfile> --label bug --label "priority:high" \
+  --assignee <user>            # only when the task specifies one
+```
+
+Write the body to a temp file (scratchpad) and use `--body-file` to avoid
+shell-quoting damage. Report the created URL.
+
+## Update an issue
+
+1. **Fetch current state**: `gh issue view <n> --json title,body,state,labels,comments,assignees`.
+2. **Verify actual progress against evidence** — diff the issue's claims
+   against live code: run `pk:scout` on the affected paths, check
+   `git log --oneline -10 -- <paths>`, and linked PR states
+   (`gh pr view <ref> --json state,mergedAt`). Do not trust checkbox state or
+   old comments; verify each item.
+3. **Update the TODO checklist** in the body: mark verified-done items
+   `- [x]` with the proving commit/PR link appended; leave unproven items
+   unchecked; add newly discovered work as new items.
+4. **Summarize what remains to implement** in a progress comment: done (with
+   evidence links), remaining (ordered), blockers/questions.
+
+```bash
+gh issue edit <n> --body-file <updated-body>
+gh issue comment <n> --body-file <progress-summary>
+gh issue edit <n> --add-label "..." --remove-label "..."   # keep labels current
+```
+
+## Close an issue
+
+1. **Full review pass**: read the entire issue — body, every checklist item,
+   every comment, linked PRs/commits.
+2. **Verify each acceptance item** against live state (code, tests, merged
+   PRs, deployed runs). Item done = evidence exists; no evidence = not done.
+3. Decide:
+   - **All items verified done** → close with a completion comment listing
+     each item and its evidence link, then:
+     ```bash
+     gh issue close <n> --reason completed --comment "<summary>"
+     ```
+   - **Not fully done** → do NOT close. Post a comment with the exact
+     remaining task list (ordered, each with what evidence would prove it
+     done) and report that list to the user.
+   - **Obsolete/won't fix** (only when the task says so) →
+     `gh issue close <n> --reason "not planned" --comment "<why>"`.
+
+Always set the close reason explicitly. Closing someone else's issue outside
+the task's explicit target requires user confirmation.
+
+## Triage sweep (bulk)
+
+For "triage the backlog" tasks: list open issues oldest-first, apply the
+dedup/resolved checks per issue, label consistently, and report a table of
+issue → action taken → evidence. Bulk closing still requires per-issue
+verification; never close on staleness alone without the task saying so.

package/skills/github/references/pr-workflows.md

@@ -0,0 +1,89 @@
+# PR Workflows
+
+Playbooks for the PR lifecycle with `gh`. Delegate review mechanics to
+`pk:review-pr` and commit/push mechanics to `pk:git` — this reference owns
+the orchestration and the gh-specific state handling.
+
+## Create a PR
+
+1. Branch state: `git status`, `git log origin/<base>..HEAD --oneline` —
+   confirm the commits belong to this PR and nothing unrelated rides along.
+2. Push via `pk:git cp` (or `git push -u origin <branch>` when already
+   committed).
+3. Body: repo template (`.github/pull_request_template.md` or
+   `.github/PULL_REQUEST_TEMPLATE/`) wins; otherwise `assets/templates/pr-body.md`.
+   Fill with evidence: what changed, why, test output, linked issue
+   (`Closes #N`). Prose in resolved language; conventional-commit title in
+   English.
+4. Create as draft by default when CI has not run yet:
+
+```bash
+gh pr create --draft --base <base> --title "feat(scope): ..." --body-file <tmpfile>
+gh pr ready <n>          # once CI is green and body is final
+```
+
+## Review a PR
+
+Activate `pk:review-pr <ref>` — it owns the full review protocol
+(correctness, security, breaking changes, anti-slop), plus `--fix` (fix
+loop), `--reply` (post formal review), `--merge` (merge + watch CI).
+Do not reimplement review logic here.
+
+For a security-focused pass, additionally activate `pk:security` scoped to
+the PR's changed files and attach its findings to the review as evidence.
+
+## Update / rebase a PR branch
+
+Check mergeability first — decide from live state, not assumption:
+
+```bash
+gh pr view <n> --json state,mergeable,mergeStateStatus,baseRefName,headRefName
+```
+
+- `mergeable: CONFLICTING` → resolve locally: `git fetch origin <base>`,
+  then merge the base into the head (or rebase when the repo convention is
+  linear history), fix conflicts, run affected tests, push. Never resolve
+  conflicts blind on the web UI.
+- Behind but clean (`mergeStateStatus: BEHIND`) → `gh pr update-branch <n>`
+  (add `--rebase` for linear-history repos). This triggers a fresh CI run;
+  in strict-status repos, update only the PR whose turn it is to merge —
+  mass-updating parallel PRs burns CI and re-invalidates them in a loop.
+
+## Merge / auto-merge
+
+Merge readiness gate (all must hold; verify, do not assume):
+
+```bash
+gh pr view <n> --json state,mergeable,reviewDecision,statusCheckRollup
+gh pr checks <n>
+```
+
+- state `OPEN`, `mergeable` clean, no `CHANGES_REQUESTED`, required checks
+  passing (pending is acceptable only with auto-merge).
+- Respect the repo's merge method (`gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed`
+  and linear-history protection). Squash is required in squash-only repos.
+
+```bash
+gh pr merge <n> --squash --auto     # auto-merge: merges when checks pass
+gh pr merge <n> --squash            # immediate, only when checks already green
+```
+
+Enable auto-merge when checks are pending instead of polling. After an
+immediate merge, watch post-merge CI on the target branch for the merge
+commit until every required check concludes (`gh run list --branch <base> --commit <sha>`,
+`gh run watch <id>`); a red post-merge run is your follow-up, not someone
+else's. Prefer `pk:review-pr <ref> --merge` / `pk:git merge-pr` when
+installed — they own the watch-and-fix loop.
+
+Never merge red/stale evidence; never bypass branch protection; a cancelled
+check is not a pass — rerun it (`gh run rerun <id> --failed`).
+
+## PR state debugging
+
+| Symptom | Check | Fix |
+|---------|-------|-----|
+| Merge button blocked | `gh pr view --json mergeStateStatus` | `BLOCKED`=missing review/check; `BEHIND`=update branch; `DIRTY`=conflicts |
+| Checks not starting | `gh run list --branch <head>` | Workflow path filters, or `gh workflow enable` |
+| Auto-merge silently off | `gh pr view --json autoMergeRequest` | Re-enable after force-push; verify repo allows auto-merge |
+| Approval reset after push | repo setting "dismiss stale reviews" | Expected cost; re-request review, never hold a fix to keep approval |
+| Draft cannot merge | `gh pr view --json isDraft` | `gh pr ready <n>` |

package/skills/github/references/projects-actions.md

@@ -0,0 +1,92 @@
+# GitHub Projects & Actions
+
+## GitHub Projects (v2)
+
+Projects v2 is the current model — items, fields, views. The legacy
+`gh api /projects` REST endpoints are deprecated; use `gh project` (GraphQL
+under the hood). Requires the `project` scope: if commands fail with
+authorization errors, report that `gh auth refresh -s project` is needed —
+do not silently retry.
+
+### Discover before mutating
+
+```bash
+gh project list --owner <org-or-user>
+gh project view <number> --owner <owner>
+gh project field-list <number> --owner <owner>       # field IDs for edits
+gh project item-list <number> --owner <owner> --limit 50 --format json
+```
+
+### Common mutations
+
+```bash
+# Add an existing issue/PR to a board
+gh project item-add <number> --owner <owner> --url <issue-or-pr-url>
+
+# Draft item (idea not yet an issue)
+gh project item-create <number> --owner <owner> --title "..." --body "..."
+
+# Move status (single-select field): need project-id, item-id, field-id, option-id
+gh project item-edit --project-id <PID> --id <ITEM_ID> \
+  --field-id <FIELD_ID> --single-select-option-id <OPT_ID>
+
+gh project item-archive <number> --owner <owner> --id <ITEM_ID>
+```
+
+IDs come from the `--format json` outputs above; never guess them. For bulk
+board syncs, fetch the item list once, compute the delta, and report the
+planned mutations before applying when >10 items change.
+
+## GitHub Actions CI/CD
+
+### Inspect runs
+
+```bash
+gh run list --limit 10                          # recent runs, any workflow
+gh run list --workflow <file.yml> --branch <b>  # scoped
+gh run view <run-id>                            # job summary + conclusions
+gh run view <run-id> --log-failed               # only failing steps' logs
+gh run watch <run-id> --exit-status             # block until done, exit code = conclusion
+```
+
+Diagnosis discipline: fetch `--log-failed` and quote the exact failing lines
+as evidence before concluding anything. A failure that also reproduces on the
+base branch predates the change — verify with
+`gh run list --branch <base> --workflow <wf>` before blaming the PR. To fix a
+diagnosed failure in code, activate `pk:fix` with the run URL, job name, and
+log excerpt.
+
+### Rerun / dispatch
+
+```bash
+gh run rerun <run-id> --failed     # rerun failed jobs, same SHA (preferred)
+gh run rerun <run-id>              # full rerun, same SHA
+gh workflow run <file.yml> --ref <branch> -f key=value   # workflow_dispatch
+gh workflow list                   # includes disabled state
+gh workflow enable|disable <file.yml>
+```
+
+Rules: `--failed` beats full rerun (cheaper, same head SHA so evidence stays
+comparable). A cancelled run is never a pass. After `gh workflow run`, find
+the spawned run via `gh run list --workflow <file.yml> --limit 1` and watch
+it — dispatching without watching is an unverified claim.
+
+### Workflow file changes
+
+Editing `.github/workflows/*.yml` is a code change: branch + PR, never a
+direct push to a protected branch. Validate syntax locally when possible
+(`actionlint` if installed). Pin third-party actions to a SHA in
+security-sensitive repos. Secrets in workflows: reference by name
+(`${{ secrets.NAME }}`); adding the secret itself is an admin operation —
+see `admin-operations.md`.
+
+### Failure triage table
+
+| Symptom | Check | Likely cause |
+|---------|-------|--------------|
+| Run not triggered | `gh workflow list`; `on:` filters | Disabled workflow, path/branch filter |
+| `startup_failure` | `gh run view <id>` | Workflow YAML syntax error |
+| Job queued forever | runner labels in YAML | No matching runner online |
+| Secret empty in run | `gh secret list` at repo + env level | Secret set at wrong scope, or fork PR (secrets withheld) |
+| Works locally, fails in CI | runner OS/env in job logs | Env/OS mismatch, missing setup step |
+| Fails only on merge to base | compare `gh run list --branch <base>` | Semantic conflict with newer base commits |

package/skills/gkg/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: pk:gkg
+description: Semantic code analysis with GitLab Knowledge Graph. Use for go-to-definition, find-usages, impact analysis, architecture visualization. Supports Ruby, Java, Kotlin, Python, TypeScript/JavaScript.
+user-invocable: true
+when_to_use: "Invoke for semantic code navigation and impact analysis."
+category: dev-tools
+keywords: [code-analysis, knowledge-graph, gitlab]
+argument-hint: "[symbol or query]"
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+# GitLab Knowledge Graph (GKG)
+
+Semantic code analysis engine using AST parsing and KuzuDB graph database. Enables IDE-like code navigation for AI assistants.
+
+**Status**: Public beta | **Requires**: Git repository | **Storage**: `~/.gkg/`
+
+## When to Use
+
+- Find all usages of a function/class across codebase
+- Go-to-definition for symbols
+- Impact analysis before refactoring
+- Generate architecture diagrams
+- RAG-enhanced code understanding
+
+**Use repomix instead** for: quick context dumps, any-language support, remote repos, token counting.
+
+## Quick Start
+
+```bash
+# Check installation
+gkg --version
+
+# Index current repo
+gkg index
+
+# Start server (for API/MCP)
+gkg server start
+
+# Stop before re-indexing
+gkg server stop
+```
+
+## Installation
+
+```bash
+# macOS/Linux
+curl -fsSL https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.sh | bash
+
+# Windows (PowerShell)
+irm https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.ps1 | iex
+```
+
+## Core Workflows
+
+### Index and Query
+```bash
+gkg index /path/to/project --stats
+gkg server start
+# Query via HTTP API at http://localhost:27495
+```
+
+### Find Symbol Usages
+1. Index project: `gkg index`
+2. Start server: `gkg server start`
+3. Use MCP tool `get_references` or HTTP API `/api/graph/search`
+
+### Impact Analysis
+1. Index affected repos
+2. Query `get_references` for changed symbols
+3. Review all call sites before refactoring
+
+## Language Support
+
+| Language | Cross-file Refs |
+|----------|-----------------|
+| Ruby | ✅ Full |
+| Java | ✅ Full |
+| Kotlin | ✅ Full |
+| Python | 🚧 In progress |
+| TypeScript | 🚧 In progress |
+| JavaScript | 🚧 In progress |
+
+## References
+
+- [CLI Commands](./references/cli-commands.md) - `gkg index`, `gkg server`, `gkg remove`, `gkg clean`
+- [MCP Tools](./references/mcp-tools.md) - 7 tools for AI integration
+- [HTTP API](./references/http-api.md) - REST endpoints for querying
+- [Language Details](./references/language-support.md) - Supported features per language
+
+## Key Constraints
+
+- Must stop server before re-indexing
+- Requires initialized Git repository
+- Languages not connected across repos (yet)
+- TS/JS/Python cross-file refs incomplete

package/skills/gkg/references/cli-commands.md

@@ -0,0 +1,106 @@
+# GKG CLI Commands
+
+## gkg index
+
+Index repositories into knowledge graph.
+
+```bash
+# Index current directory
+gkg index
+
+# Index specific path
+gkg index /path/to/workspace
+
+# With statistics output
+gkg index --stats
+
+# Save stats as JSON
+gkg index --stats stats.json
+
+# Verbose logging
+gkg index -v
+
+# Control thread count (default: CPU cores)
+gkg index --threads 4
+```
+
+**Auto-detection**: Detects if path is workspace (multiple repos) or single repository.
+
+**Output location**: `~/.gkg/{workspace_hash}/{project_hash}/`
+
+## gkg server
+
+Start HTTP server for API and MCP access.
+
+```bash
+# Start server (default: http://localhost:27495)
+gkg server start
+
+# Start with MCP endpoints
+gkg server start --register-mcp
+
+# Stop server
+gkg server stop
+
+# Check status
+gkg server status
+```
+
+**Port**: 27495 (0x6b67 = "kg" in hex). Falls back to unused port if busy.
+
+**Important**: Stop server before re-indexing: `gkg server stop`
+
+## gkg remove
+
+Remove indexed data.
+
+```bash
+# Remove entire workspace
+gkg remove --workspace /path/to/workspace
+
+# Remove single project
+gkg remove --project /path/to/project --workspace-folder /path/to/workspace
+```
+
+## gkg clean
+
+Clean orphaned or corrupted data.
+
+```bash
+# Clean all orphaned data
+gkg clean
+
+# Dry run (preview only)
+gkg clean --dry-run
+```
+
+## Common Workflows
+
+### Initial Setup
+```bash
+cd /my/project
+gkg index --stats
+gkg server start
+```
+
+### Re-index After Changes
+```bash
+gkg server stop
+gkg index
+gkg server start
+```
+
+### Multi-repo Workspace
+```bash
+# Index parent directory containing multiple repos
+gkg index /path/to/workspace
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| High memory | Reduce `--threads` |
+| Slow indexing | Increase `--threads` or use `-v` |
+| Server conflict | Run `gkg server stop` first |
+| Stale data | Run `gkg clean` |

package/skills/gkg/references/http-api.md

@@ -0,0 +1,102 @@
+# GKG HTTP API
+
+Base URL: `http://localhost:27495`
+
+## Server Info
+
+```
+GET /api/info
+```
+Returns port, version.
+
+## Workspace Management
+
+### List Workspaces
+```
+GET /api/workspace/list
+```
+Returns all indexed workspaces and projects.
+
+### Index Workspace
+```
+POST /api/workspace/index
+Content-Type: application/json
+
+{"path": "/path/to/workspace"}
+```
+Index or re-index workspace.
+
+### Delete Workspace
+```
+DELETE /api/workspace/delete
+Content-Type: application/json
+
+{"path": "/path/to/workspace"}
+```
+
+### Delete Project
+```
+DELETE /api/project/delete
+Content-Type: application/json
+
+{
+  "project_path": "/path/to/project",
+  "workspace_path": "/path/to/workspace"
+}
+```
+
+## Graph Queries
+
+### Initial Graph Data
+```
+GET /api/graph/initial?project=/path/to/project
+```
+Fetch visualization starting data.
+
+### Neighbors
+```
+GET /api/graph/neighbors?node_id=xxx&project=/path
+```
+Get connected nodes for exploration.
+
+### Search
+```
+GET /api/graph/search?pattern=MyClass&project=/path
+```
+Search definitions by pattern.
+
+### Statistics
+```
+GET /api/graph/stats?project=/path
+```
+Returns: files, definitions, relationships counts.
+
+## Real-time Events
+
+```
+GET /api/events
+```
+Server-Sent Events stream. Event types:
+- `gkg-connection`: Connection status
+- `gkg-event`: Indexing progress updates
+
+## Error Handling
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Success |
+| 400 | Bad request |
+| 404 | Not found |
+| 500 | Server error |
+
+Response format:
+```json
+{
+  "error": "message",
+  "code": "ERROR_CODE"
+}
+```
+
+## CORS
+
+Accepts localhost origins. No authentication required locally.

package/skills/gkg/references/language-support.md

@@ -0,0 +1,57 @@
+# GKG Language Support
+
+## Support Matrix
+
+| Language | Definitions | Imports | Intra-file Refs | Cross-file Refs |
+|----------|-------------|---------|-----------------|-----------------|
+| Ruby | ✅ | ✅ | ✅ | ✅ |
+| Java | ✅ | ✅ | ✅ | ✅ |
+| Kotlin | ✅ | ✅ | ✅ | ✅ |
+| Python | ✅ | ✅ | ✅ | 🚧 |
+| TypeScript | ✅ | ✅ | ✅ | 🚧 |
+| JavaScript | ✅ | ✅ | ✅ | 🚧 |
+
+## Feature Definitions
+
+**Definitions**: Classes, functions, methods, constants, interfaces extracted from AST.
+
+**Imports**: Module/package imports tracked for dependency analysis.
+
+**Intra-file Refs**: References to symbols within same file.
+
+**Cross-file Refs**: References to symbols defined in other files. Critical for impact analysis.
+
+## Fully Supported (Ruby, Java, Kotlin)
+
+Complete semantic analysis:
+- Go-to-definition across files
+- Find all usages across codebase
+- Full dependency graph
+- Impact analysis for refactoring
+
+## Partially Supported (Python, TS/JS)
+
+Current capabilities:
+- Definition extraction works
+- Import tracking works
+- Same-file reference tracking works
+
+Limitations:
+- Cross-file `get_references` may miss some usages
+- `get_definition` may not resolve all external symbols
+- Use with awareness of gaps
+
+## Best Practices
+
+### For Full Support Languages
+Use all MCP tools confidently for complete analysis.
+
+### For Partial Support Languages
+1. Verify critical refactoring impacts manually
+2. Use `search_codebase_definitions` for discovery
+3. Cross-reference with `grep` for completeness
+4. Supplement with repomix for context dumps
+
+## Future Plans
+
+Cross-file reference support for Python/TS/JS under active development. Check [GitLab Knowledge Graph](https://gitlab.com/gitlab-org/rust/knowledge-graph) for updates.