shmakk 1.1.0 → 1.2.0

package/skills/dev-github-issues.md

@@ -0,0 +1,202 @@
+---
+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, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.'
+category: dev
+---
+
+# GitHub Issues
+
+Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.
+
+## Available Tools
+
+### MCP Tools (read operations)
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) |
+| `mcp__github__list_issues` | List and filter repository issues by state, labels, date |
+| `mcp__github__search_issues` | Search issues across repos using GitHub search syntax |
+| `mcp__github__projects_list` | List projects, project fields, project items, status updates |
+| `mcp__github__projects_get` | Get details of a project, field, item, or status update |
+| `mcp__github__projects_write` | Add/update/delete project items, create status updates |
+
+### CLI / REST API (write operations)
+
+The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations.
+
+| Operation | Command |
+|-----------|---------|
+| Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` |
+| Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` |
+| Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` |
+| Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` |
+| Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) |
+
+**Note:** `gh issue create` works for basic issue creation but does **not** support the `--type` flag. Use `gh api` when you need to set issue types.
+
+## 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 MCP tools for reads, `gh api` for writes
+5. **Confirm**: Report the issue URL to user
+
+## Creating Issues
+
+Use `gh api` to create issues. This supports all parameters including issue types.
+
+```bash
+gh api repos/{owner}/{repo}/issues \
+  -X POST \
+  -f title="Issue title" \
+  -f body="Issue body in markdown" \
+  -f type="Bug" \
+  --jq '{number, html_url}'
+```
+
+### Optional Parameters
+
+Add any of these flags to the `gh api` call:
+
+```
+-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
+-f labels[]="bug"                # Labels (repeat for multiple)
+-f assignees[]="username"        # Assignees (repeat for multiple)
+-f milestone=1                   # Milestone number
+```
+
+**Issue types** are organization-level metadata. To discover available types, use:
+```bash
+gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'
+```
+
+**Prefer issue types over labels for categorization.** When issue types are available (e.g., Bug, Feature, Task), use the `type` parameter instead of applying equivalent labels like `bug` or `enhancement`. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured.
+
+### Title Guidelines
+
+- Be specific and actionable
+- Keep under 72 characters
+- When issue types are set, don't add redundant prefixes like `[Bug]`
+- Examples:
+  - `Login fails with SSO enabled` (with type=Bug)
+  - `Add dark mode support` (with type=Feature)
+  - `Add unit tests for auth module` (with type=Task)
+
+### 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 `gh api` with PATCH:
+
+```bash
+gh api repos/{owner}/{repo}/issues/{number} \
+  -X PATCH \
+  -f state=closed \
+  -f title="Updated title" \
+  --jq '{number, html_url}'
+```
+
+Only include fields you want to change. Available fields: `title`, `body`, `state` (open/closed), `labels`, `assignees`, `milestone`.
+
+## Examples
+
+### Example 1: Bug Report
+
+**User**: "Create a bug issue - the login page crashes when using SSO"
+
+**Action**: 
+```bash
+gh api repos/github/awesome-copilot/issues \
+  -X POST \
+  -f title="Login page crashes when using SSO" \
+  -f type="Bug" \
+  -f body="## Description
+The login page crashes when users attempt to authenticate using SSO.
+
+## Steps to Reproduce
+1. Navigate to login page
+2. Click 'Sign in with SSO'
+3. Page crashes
+
+## Expected Behavior
+SSO authentication should complete and redirect to dashboard.
+
+## Actual Behavior
+Page becomes unresponsive and displays error." \
+  --jq '{number, html_url}'
+```
+
+### Example 2: Feature Request
+
+**User**: "Create a feature request for dark mode with high priority"
+
+**Action**:
+```bash
+gh api repos/github/awesome-copilot/issues \
+  -X POST \
+  -f title="Add dark mode support" \
+  -f type="Feature" \
+  -f labels[]="high-priority" \
+  -f body="## Summary
+Add dark mode theme option for improved user experience and accessibility.
+
+## Motivation
+- Reduces eye strain in low-light environments
+- Increasingly expected by users
+
+## Proposed Solution
+Implement theme toggle with system preference detection.
+
+## Acceptance Criteria
+- [ ] Toggle switch in settings
+- [ ] Persists user preference
+- [ ] Respects system preference by default" \
+  --jq '{number, html_url}'
+```
+
+## 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
+
+## Extended Capabilities
+
+The following features require REST or GraphQL APIs beyond the basic MCP tools. Each is documented in its own reference file so the agent only loads the knowledge it needs.
+
+| Capability | When to use | Reference |
+|------------|-------------|-----------|
+| Advanced search | Complex queries with boolean logic, date ranges, cross-repo search, issue field filters (`field.name:value`) | [references/search.md](references/search.md) |
+| Sub-issues & parent issues | Breaking work into hierarchical tasks | [references/sub-issues.md](references/sub-issues.md) |
+| Issue dependencies | Tracking blocked-by / blocking relationships | [references/dependencies.md](references/dependencies.md) |
+| Issue types (advanced) | GraphQL operations beyond MCP `list_issue_types` / `type` param | [references/issue-types.md](references/issue-types.md) |
+| Projects V2 | Project boards, progress reports, field management | [references/projects.md](references/projects.md) |
+| Issue fields | Custom metadata: dates, priority, text, numbers (private preview) | [references/issue-fields.md](references/issue-fields.md) |
+| Images in issues | Embedding images in issue bodies and comments via CLI | [references/images.md](references/images.md) |

package/skills/dev-gpt-5-4-prompting.md

@@ -0,0 +1,55 @@
+---
+name: gpt-5-4-prompting
+description: Internal guidance for composing Codex and GPT-5.4 prompts for coding, review, diagnosis, and research tasks inside the Codex Claude Code plugin
+user-invocable: false
+category: dev
+---
+
+# GPT-5.4 Prompting
+
+Use this skill when `codex:codex-rescue` needs to ask Codex or another GPT-5.4-based workflow for help.
+
+Prompt Codex like an operator, not a collaborator. Keep prompts compact and block-structured with XML tags. State the task, the output contract, the follow-through defaults, and the small set of extra constraints that matter.
+
+Core rules:
+- Prefer one clear task per Codex run. Split unrelated asks into separate runs.
+- Tell Codex what done looks like. Do not assume it will infer the desired end state.
+- Add explicit grounding and verification rules for any task where unsupported guesses would hurt quality.
+- Prefer better prompt contracts over raising reasoning or adding long natural-language explanations.
+- Use XML tags consistently so the prompt has stable internal structure.
+
+Default prompt recipe:
+- `<task>`: the concrete job and the relevant repository or failure context.
+- `<structured_output_contract>` or `<compact_output_contract>`: exact shape, ordering, and brevity requirements.
+- `<default_follow_through_policy>`: what Codex should do by default instead of asking routine questions.
+- `<verification_loop>` or `<completeness_contract>`: required for debugging, implementation, or risky fixes.
+- `<grounding_rules>` or `<citation_rules>`: required for review, research, or anything that could drift into unsupported claims.
+
+When to add blocks:
+- Coding or debugging: add `completeness_contract`, `verification_loop`, and `missing_context_gating`.
+- Review or adversarial review: add `grounding_rules`, `structured_output_contract`, and `dig_deeper_nudge`.
+- Research or recommendation tasks: add `research_mode` and `citation_rules`.
+- Write-capable tasks: add `action_safety` so Codex stays narrow and avoids unrelated refactors.
+
+How to choose prompt shape:
+- Use built-in `review` or `adversarial-review` commands when the job is reviewing local git changes. Those prompts already carry the review contract.
+- Use `task` when the task is diagnosis, planning, research, or implementation and you need to control the prompt more directly.
+- Use `task --resume-last` for follow-up instructions on the same Codex thread. Send only the delta instruction instead of restating the whole prompt unless the direction changed materially.
+
+Working rules:
+- Prefer explicit prompt contracts over vague nudges.
+- Use stable XML tag names that match the block names from the reference file.
+- Do not raise reasoning or complexity first. Tighten the prompt and verification rules before escalating.
+- Ask Codex for brief, outcome-based progress updates only when the task is long-running or tool-heavy.
+- Keep claims anchored to observed evidence. If something is a hypothesis, say so.
+
+Prompt assembly checklist:
+1. Define the exact task and scope in `<task>`.
+2. Choose the smallest output contract that still makes the answer easy to use.
+3. Decide whether Codex should keep going by default or stop for missing high-risk details.
+4. Add verification, grounding, and safety tags only where the task needs them.
+5. Remove redundant instructions before sending the prompt.
+
+Reusable blocks live in [references/prompt-blocks.md](references/prompt-blocks.md).
+Concrete end-to-end templates live in [references/codex-prompt-recipes.md](references/codex-prompt-recipes.md).
+Common failure modes to avoid live in [references/codex-prompt-antipatterns.md](references/codex-prompt-antipatterns.md).

package/skills/dev-investigation-mode.md

@@ -0,0 +1,277 @@
+---
+name: investigation-mode
+description: "Orchestrated debugging coordinator. Triggers on frustration signals (stuck, hung, broken, waiting) and systematically triages: runtime logs → workflow status → browser verify → deploy/env. Reports findings at every step."
+metadata:
+  priority: 8
+  docs:
+    - "https://openai.com/index/introducing-codex/"
+  pathPatterns:
+    - "**/middleware.{ts,js,mjs}"
+    - "**/lib/logger.{ts,js}"
+    - "**/utils/logger.{ts,js}"
+    - "**/instrumentation.{ts,js}"
+    - "**/*.log"
+    - "**/error.{tsx,ts,js,jsx}"
+    - "**/global-error.{tsx,ts,js,jsx}"
+    - "**/not-found.{tsx,ts,js,jsx}"
+  bashPatterns:
+    - '\bvercel\s+logs?\b'
+    - '\bvercel\s+inspect\b'
+    - '\btail\s+-f\b.*\.log'
+    - '\bworkflow\s+runs?\b'
+    - '\bvercel\s+ls\b'
+    - '\bcurl\s+-[vI]'
+  importPatterns: []
+  promptSignals:
+    phrases:
+      - "nothing happened"
+      - "still waiting"
+      - "it's stuck"
+      - "it's hung"
+      - "nothing is happening"
+      - "not responding"
+      - "just sitting there"
+      - "just sits there"
+      - "seems frozen"
+      - "is it frozen"
+      - "frozen"
+      - "why is it hanging"
+      - "check the logs"
+      - "check logs"
+      - "where are the logs"
+      - "how do I debug"
+      - "how to debug"
+      - "white screen"
+      - "blank page"
+      - "spinning forever"
+      - "timed out"
+      - "keeps timing out"
+      - "no response"
+      - "no output"
+      - "not loading"
+      - "debug this"
+      - "investigate why"
+      - "what went wrong"
+      - "why did it fail"
+      - "why is it failing"
+      - "something is broken"
+      - "something broke"
+      - "seems broken"
+      - "check what happened"
+      - "check the status"
+      - "where is the error"
+      - "where did it fail"
+      - "find the error"
+      - "show me the error"
+      - "why is it slow"
+      - "taking forever"
+      - "still loading"
+      - "not finishing"
+      - "seems dead"
+      - "been waiting"
+      - "waiting forever"
+      - "stuck on"
+      - "hung up"
+      - "not progressing"
+      - "stalled out"
+      - "is it running"
+      - "did it crash"
+      - "keeps failing"
+      - "why no response"
+      - "where did it go"
+      - "lost connection"
+      - "never finishes"
+      - "pending forever"
+      - "queue stuck"
+      - "job stuck"
+      - "build stuck"
+      - "request hanging"
+      - "api not responding"
+    allOf:
+      - [stuck, workflow]
+      - [stuck, deploy]
+      - [stuck, loading]
+      - [stuck, build]
+      - [stuck, queue]
+      - [stuck, job]
+      - [hung, request]
+      - [hung, api]
+      - [frozen, page]
+      - [frozen, app]
+      - [check, why]
+      - [check, broken]
+      - [check, error]
+      - [check, status]
+      - [check, logs]
+      - [debug, workflow]
+      - [debug, deploy]
+      - [debug, api]
+      - [debug, issue]
+      - [investigate, error]
+      - [logs, error]
+      - [logs, check]
+      - [slow, response]
+      - [slow, loading]
+      - [timeout, api]
+      - [timeout, request]
+      - [waiting, response]
+      - [waiting, forever]
+      - [waiting, deploy]
+      - [not working, why]
+      - [not, responding]
+      - [hanging, for]
+      - [been, hanging]
+      - [been, stuck]
+      - [been, waiting]
+      - [why, slow]
+      - [why, failing]
+      - [why, stuck]
+      - [why, hanging]
+      - [job, failing]
+      - [queue, processing]
+    anyOf:
+      - "stuck"
+      - "hung"
+      - "frozen"
+      - "broken"
+      - "failing"
+      - "timeout"
+      - "slow"
+      - "debug"
+      - "investigate"
+      - "check"
+      - "logs"
+      - "error"
+      - "hanging"
+      - "waiting"
+      - "stalled"
+      - "pending"
+      - "processing"
+      - "loading"
+      - "unresponsive"
+    noneOf:
+      - "css stuck"
+      - "sticky position"
+      - "position: sticky"
+      - "z-index"
+      - "sticky nav"
+      - "sticky header"
+      - "sticky footer"
+      - "overflow: hidden"
+      - "add a button"
+      - "create a button"
+      - "style the button"
+    minScore: 4
+category: dev
+---
+
+# Investigation Mode — Orchestrated Debugging
+
+When a user reports something stuck, hung, broken, or not responding, you are the **diagnostic coordinator**. Do not guess. Follow the triage order, report what you find at every step, and stop when you have a high-confidence root cause.
+
+## Reporting Contract
+
+Every investigation step MUST follow this pattern:
+
+1. **Tell the user what you are checking** — "I'm checking the runtime logs for errors…"
+2. **Share the evidence you found** — paste the relevant log line, status, error, or screenshot
+3. **Explain the next step** — "The logs show a timeout on the DB call. I'll check the connection pool next."
+
+Never silently move between steps. The user is already frustrated — silence makes it worse.
+
+## Triage Order
+
+Work through these in order. Stop as soon as you find the root cause.
+
+### 1. Runtime Logs (check first — most issues leave traces here)
+
+- **Dev server**: Check terminal output for errors, warnings, unhandled rejections
+- **Vercel logs**: `vercel logs --follow` (production) or `vercel logs <deployment-url>`
+- **Browser console**: Open DevTools → Console tab for client-side errors
+- **If no logs exist**: This is the problem. Add logging before continuing (see "Add Logging" below)
+
+Tell the user: "Checking runtime logs…" → share what you found → explain next step.
+
+### 2. Workflow / Background Job Status
+
+If the app uses workflows, queues, or cron jobs:
+
+- Run `vercel workflow runs list` to check recent run statuses
+- Look for runs stuck in `running` state — likely a missing `await` or unresolved promise
+- Check individual run details: `vercel workflow runs get <run-id>`
+- Look for failed steps, retry exhaustion, or timeout errors
+
+Tell the user: "Checking workflow run status…" → share the run state → explain next step.
+
+### 3. Browser Verification
+
+Use agent-browser to visually verify what the user sees:
+
+- Take a screenshot of the current page state
+- Check the browser console for JavaScript errors
+- Check the Network tab for failed requests (4xx/5xx, CORS errors, hanging requests)
+- Look for hydration mismatches or React error boundaries
+
+Tell the user: "Taking a browser screenshot to see the current state…" → share the screenshot → explain what you see.
+
+### 4. Deploy / Environment Status
+
+- `vercel inspect <deployment-url>` — check build output, function regions, environment
+- `vercel ls` — verify the latest deployment succeeded
+- Check for environment variable mismatches between local and production
+- Verify the correct branch/commit is deployed
+
+Tell the user: "Checking deployment status…" → share the deployment state → explain findings.
+
+## Stop Condition
+
+**Stop investigating when:**
+- You find a high-confidence root cause (specific error, missing env var, failed step, etc.)
+- Two consecutive triage steps produce no signal — report what you checked and that you found no evidence, then ask the user for more context
+
+**Do not** keep cycling through steps hoping something appears. If logs are empty and workflows look fine, say so and ask the user what they expected to happen.
+
+## Common Hang Causes
+
+When logs point to code issues, check for these frequent culprits:
+
+- **Missing `await`**: Async functions called without await cause silent failures
+- **Infinite loops**: `while(true)` without break conditions, recursive calls without base cases
+- **Unresolved promises**: `new Promise()` that never calls `resolve()` or `reject()`
+- **Missing env vars**: `process.env.X` returning `undefined` causing silent auth/DB failures
+- **Connection pool exhaustion**: Database connections not being released
+- **Middleware chains**: A middleware that never calls `next()` or returns a response
+- **Timeout misconfigs**: Function timeout too short for the operation (check `vercel.json` maxDuration)
+
+## Add Logging (If Missing)
+
+If the investigation reveals insufficient observability, **add structured logging immediately** — you cannot debug what you cannot see.
+
+```typescript
+// API routes — wrap handlers with try/catch + logging
+export async function POST(request: Request) {
+  console.log('[api/route] incoming request', { method: 'POST', url: request.url });
+  try {
+    const result = await doWork();
+    console.log('[api/route] success', { resultId: result.id });
+    return Response.json(result);
+  } catch (error) {
+    console.error('[api/route] failed', { error: String(error), stack: (error as Error).stack });
+    return Response.json({ error: 'Internal error' }, { status: 500 });
+  }
+}
+```
+
+```typescript
+// Workflow steps — log entry/exit of every step
+const result = await step.run('process-data', async () => {
+  console.log('[workflow:process-data] step started');
+  const data = await fetchData();
+  console.log('[workflow:process-data] step completed', { count: data.length });
+  return data;
+});
+```
+
+**Key principle**: Every async boundary, every external call, every step entry/exit should have a log line. When something hangs, the last log line tells you exactly where it stopped.
+
+> **Cross-reference**: For comprehensive logging setup (OpenTelemetry, log drains, Sentry, Vercel Analytics), see the **observability** skill. For workflow-specific debugging, see the **workflow** skill.