@mrciphersmith/keryx 0.2.72 → 0.2.74

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.cursor.md

@@ -1,18 +1,15 @@
 ---
-name: gproject-stack-advisor
-description: "Determines project level (MVP/pet/startup/production) and recommends optimal technology stack with trade-off analysis. Use when: dispatched by gproject-orchestrator Phase 2."
-triggers:
-  - "gproject-stack-advisor: select stack"
-  - "Dispatched by gproject-orchestrator Phase 2"
+name: stack-advisor
+description: >
+  Determines project level (MVP/pet/startup/production) and recommends optimal
+  technology stack with trade-off analysis.
+  Use when: dispatched by gproject-orchestrator Phase 2.
+  NOT for: direct user invocation.
 metadata:
-  author: "MrCipherSmith"
-  version: "1.0.0"
-  category: "planning"
+  version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
-license: "MIT"
 ---
 
-
 # gproject-stack-advisor
 
 ## Purpose
@@ -41,3 +38,158 @@ with trade-offs — not "use React because it's popular" but "use React because
 | Ignoring team skills in rationale | Tech-driven not people-driven | Re-evaluate with team factor |
 | No alternative considered | Confirmation bias | Research at least 1 alternative per choice |
 | Recommending bleeding-edge for production | Risk ignorance | Flag maturity concern |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Select project level and technology stack"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/problem-statement.md
+decisions_so_far:
+  D_core_problems: [...]
+  D_goals: [...]
+  D_non_goals: [...]
+  D_target_users: "..."
+  D_scale_estimate: "..."
+  # For task_in_project:
+  D_existing_stack: "<if detected by context-collector>"
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: level chosen, stack chosen, key trade-off>"
+new_decisions:
+  D_level: "mvp | pet | startup | production"
+  D_frontend: "<framework + version>"
+  D_backend: "<framework + version>"
+  D_database: "<DB + version>"
+  D_cache: "<if needed>"
+  D_queue: "<if needed>"
+  D_auth: "<approach>"
+  D_deploy: "<strategy>"
+  D_infra: "<approach>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/stack-decision.md"
+next_phase_needs:
+  - "Per-technology best practices research"
+  - "Architecture pattern selection"
+```
+
+---
+
+## Workflow
+
+### Step 1: Determine Project Level
+
+Evaluate against criteria matrix:
+
+| Factor | MVP | Pet/Learning | Startup | Production |
+|--------|-----|-------------|---------|------------|
+| Users | <100 | 1 (self) | 100-10K | 10K+ |
+| Team | 1 person | 1 person | 2-5 | 5+ |
+| Lifespan | weeks | indefinite | months-years | years |
+| Budget | minimal | zero | seed/limited | funded |
+| Uptime SLA | none | none | 99% | 99.9%+ |
+| Data sensitivity | low | low | medium | high |
+| Compliance | none | none | basic | regulated |
+
+The level determines complexity ceiling:
+- **MVP**: max simplicity, monolith, single deploy target, minimal infra
+- **Pet**: developer experience priority, learning-friendly stack
+- **Startup**: balance of speed and scalability, ready for growth
+- **Production**: reliability, security, observability, scalability first
+
+### Step 2: Evaluate Stack Options
+
+For each layer, evaluate 2-3 options against project-specific criteria:
+
+**Evaluation criteria** (weight varies by project level):
+1. **Problem fit** — does it solve our specific problems well?
+2. **Team match** — does the team know it? Learning curve?
+3. **Ecosystem** — libraries, tools, community for our use case
+4. **Scalability ceiling** — will it handle our target scale?
+5. **Velocity** — how fast can we ship with it?
+6. **Cost** — licensing, hosting, operational cost
+7. **Maturity** — production-proven? Active maintenance?
+8. **Integration** — works well with other chosen components?
+
+### Step 3: Web Research (Best Practices)
+
+For the shortlisted stack, research:
+- Current best practices (2024-2025 sources preferred)
+- Common pitfalls and antipatterns
+- Production case studies at similar scale
+- Performance benchmarks relevant to our use case
+
+### Step 4: task_in_project Mode Adjustments
+
+If mode is task_in_project:
+- Start from existing stack (detected by context-collector)
+- Only recommend NEW technologies if:
+  - Existing stack cannot solve the specific problem
+  - New tech integrates cleanly with existing stack
+  - Learning overhead is justified by benefit
+- Flag any technology additions clearly as "NEW — requires team learning"
+
+### Step 5: Write Stack Decision
+
+Write `artifacts/stack-decision.md`:
+
+```markdown
+# Stack Decision: <Project/Task Name>
+
+## Project Level: <LEVEL>
+**Rationale**: <why this level, based on constraints>
+
+## Technology Stack
+
+### Frontend: <Choice>
+**Version**: <specific>
+**Rationale**: <tied to project constraints>
+**Alternative considered**: <what and why rejected>
+**Key libraries**: <essential deps>
+
+### Backend: <Choice>
+**Version**: <specific>
+**Rationale**: <tied to project constraints>
+**Alternative considered**: <what and why rejected>
+**Key libraries**: <essential deps>
+
+### Database: <Choice>
+...
+
+### Infrastructure & Deploy: <Choice>
+...
+
+### Additional Services (if any)
+- Cache: <if needed, with rationale>
+- Queue: <if needed, with rationale>
+- Search: <if needed, with rationale>
+
+## Stack Compatibility Matrix
+| Component | Integrates With | Integration Quality |
+|-----------|----------------|-------------------|
+| <A> | <B> | proven / good / experimental |
+
+## Trade-offs Accepted
+| Trade-off | What We Gain | What We Give Up |
+|-----------|-------------|-----------------|
+| <choice> | <benefit> | <cost> |
+
+## Complexity Budget
+**Total new technologies**: <count>
+**Team learning required**: <list what's new>
+**Estimated ramp-up**: <time>
+
+## Risk Assessment
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| <risk> | <H/M/L> | <H/M/L> | <plan> |
+```
+
+### Step 6: Return Summary
+
+Compact summary: level + core stack (one line) + biggest trade-off + confidence.

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: gproject-stack-advisor
+name: stack-advisor
 description: >
   Determines project level (MVP/pet/startup/production) and recommends optimal
   technology stack with trade-off analysis.

package/src/gdskills/bundled/skills/platform/claude-md-management/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: claude-md-management
-description: "Capture session learnings and persist into CLAUDE.md files. Extracts coding patterns, conventions, commands, and gotchas discovered during work. Classifies into project-level vs global vs personal CLAUDE.md. Shows diff preview before applying."
+description: "Use when saving session learnings, coding patterns, conventions, or commands discovered during work into CLAUDE.md files."
 triggers:
   - "/revise-claude-md"
   - "Update claude md"

package/src/gdskills/bundled/skills/platform/claude-md-management/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: claude-md-management
-description: "Capture session learnings and persist into CLAUDE.md files. Extracts coding patterns, conventions, commands, and gotchas discovered during work. Classifies into project-level vs global vs personal CLAUDE.md. Shows diff preview before applying."
+description: "Use when saving session learnings, coding patterns, conventions, or commands discovered during work into CLAUDE.md files."
 triggers:
   - "/revise-claude-md"
   - "Update claude md"

package/src/gdskills/bundled/skills/platform/hookify/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: hookify
-description: "Create Claude Code / Cursor hooks from natural language descriptions. Generates hook config JSON for settings.json with proper event matchers and commands. Supports PreToolUse, PostToolUse, Stop, Notification events."
+description: "Use when adding automated hook behavior to Claude Code or Cursor from a natural language description."
 triggers:
   - "/hookify"
   - "Create hook"

package/src/gdskills/bundled/skills/platform/hookify/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: hookify
-description: "Create Claude Code / Cursor hooks from natural language descriptions. Generates hook config JSON for settings.json with proper event matchers and commands. Supports PreToolUse, PostToolUse, Stop, Notification events."
+description: "Use when adding automated hook behavior to Claude Code or Cursor from a natural language description."
 triggers:
   - "/hookify"
   - "Create hook"

package/src/gdskills/bundled/skills/quality/changelog/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: changelog
-description: "Generate changelog from git commits between tags or date ranges. Groups by conventional commit type (features, fixes, performance, etc.), links PRs and issues. Supports output to file or prepend to existing CHANGELOG.md."
+description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges."
 triggers:
   - "/changelog"
   - "Generate changelog"

package/src/gdskills/bundled/skills/quality/changelog/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: changelog
-description: "Generate changelog from git commits between tags or date ranges. Groups by conventional commit type (features, fixes, performance, etc.), links PRs and issues. Supports output to file or prepend to existing CHANGELOG.md."
+description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges."
 triggers:
   - "/changelog"
   - "Generate changelog"

package/src/gdskills/bundled/skills/quality/commit/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: commit
-description: "Smart git commit: auto-stages changes, analyzes diff, generates conventional commit message. Supports custom messages, amend, and selective staging. Use when committing code changes with meaningful messages."
+description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging."
 triggers:
   - "/commit"
   - "Commit changes"

package/src/gdskills/bundled/skills/quality/commit/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: commit
-description: "Smart git commit: auto-stages changes, analyzes diff, generates conventional commit message. Supports custom messages, amend, and selective staging. Use when committing code changes with meaningful messages."
+description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging."
 triggers:
   - "/commit"
   - "Commit changes"

package/src/gdskills/bundled/skills/quality/db-migrate/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: db-migrate
-description: "Database migration management: create, apply, rollback, check status. Auto-detects Prisma, TypeORM, Knex, Sequelize, Drizzle, Alembic, raw SQL. Shows migration SQL preview before applying."
+description: "Use when creating, applying, rolling back, or checking the status of database migrations."
 triggers:
   - "/db-migrate"
   - "Create migration"

package/src/gdskills/bundled/skills/quality/db-migrate/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: db-migrate
-description: "Database migration management: create, apply, rollback, check status. Auto-detects Prisma, TypeORM, Knex, Sequelize, Drizzle, Alembic, raw SQL. Shows migration SQL preview before applying."
+description: "Use when creating, applying, rolling back, or checking the status of database migrations."
 triggers:
   - "/db-migrate"
   - "Create migration"

package/src/gdskills/bundled/skills/quality/dependency-update/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-update
-description: "Smart dependency updates: check outdated packages, classify by risk (patch/minor/major), update with compatibility verification. Runs tests after each major update, rollbacks on failure. Creates atomic commits per group."
+description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification."
 triggers:
   - "/dependency-update"
   - "Update dependencies"

package/src/gdskills/bundled/skills/quality/dependency-update/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-update
-description: "Smart dependency updates: check outdated packages, classify by risk (patch/minor/major), update with compatibility verification. Runs tests after each major update, rollbacks on failure. Creates atomic commits per group."
+description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification."
 triggers:
   - "/dependency-update"
   - "Update dependencies"

package/src/gdskills/bundled/skills/quality/deploy/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Automated deployment pipeline: pre-flight checks (tests, lint, type-check, build), then deploy to target environment. Auto-detects Docker Compose, PM2, SSH, Vercel, Railway. Post-deploy health verification."
+description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run."
 triggers:
   - "/deploy"
   - "Deploy to"

package/src/gdskills/bundled/skills/quality/deploy/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Automated deployment pipeline: pre-flight checks (tests, lint, type-check, build), then deploy to target environment. Auto-detects Docker Compose, PM2, SSH, Vercel, Railway. Post-deploy health verification."
+description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run."
 triggers:
   - "/deploy"
   - "Deploy to"

package/src/gdskills/bundled/skills/quality/perf-check/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: perf-check
-description: "Performance analysis: bundle size measurement, Lighthouse audit, dependency weight analysis, code-level anti-pattern detection (N+1, missing memoization, heavy imports). Produces prioritized report with optimization suggestions."
+description: "Use when measuring bundle size, detecting performance regressions, auditing slow queries, or investigating why something is slow."
 triggers:
   - "/perf-check"
   - "Check performance"

package/src/gdskills/bundled/skills/quality/perf-check/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: perf-check
-description: "Performance analysis: bundle size measurement, Lighthouse audit, dependency weight analysis, code-level anti-pattern detection (N+1, missing memoization, heavy imports). Produces prioritized report with optimization suggestions."
+description: "Use when measuring bundle size, detecting performance regressions, auditing slow queries, or investigating why something is slow."
 triggers:
   - "/perf-check"
   - "Check performance"

package/src/gdskills/bundled/skills/quality/pr/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: pr
-description: "Smart Pull Request creation: analyzes all branch commits, generates structured title and description with Summary/Changes/Test plan, creates PR via gh CLI. Auto-pushes if branch not on remote."
+description: "Use when opening a pull request for the current branch."
 triggers:
   - "/pr"
   - "Create PR"

package/src/gdskills/bundled/skills/quality/pr/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: pr
-description: "Smart Pull Request creation: analyzes all branch commits, generates structured title and description with Summary/Changes/Test plan, creates PR via gh CLI. Auto-pushes if branch not on remote."
+description: "Use when opening a pull request for the current branch."
 triggers:
   - "/pr"
   - "Create PR"

package/src/gdskills/bundled/skills/quality/pr-issue-documenter/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: pr-issue-documenter
-description: "Analyzes PR commits/diff and generates structured descriptions for PRs and linked GitHub issues. Creates sub-issues, checks for contradictions with existing descriptions, updates parent issues. Use when: documenting PR changes, adding PR description, creating issue for PR, updating issue body."
+description: "Use when documenting PR changes, adding a PR description, creating a linked issue for a PR, or updating an existing issue body."
 triggers:
   - "Add PR description"
   - "Document PR changes"
@@ -362,3 +362,17 @@ Always present contradictions to user before making changes.
 8. **DO NOT** create issues without user confirmation
 9. **DO NOT** modify PR title unless explicitly asked
 10. **DO NOT** write comments on GitHub PRs/issues (only edit body)
+
+## Job Context Awareness
+
+If called within an orchestrator job context, check for job context before starting:
+
+```
+IF JOB_NAME is provided AND .metaproject/jobs/<JOB_NAME>/ai/context.md exists:
+  Read context.md — use it to understand the codebase, affected areas, and conventions
+  This enriches PR description generation with project-specific knowledge
+ELSE:
+  Proceed with standard workflow (analyze PR/commits directly)
+```
+
+The job context path is: `<JOBS_ROOT>/<JOB_NAME>/ai/context.md`