@silverassist/agents-toolkit 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverassist/agents-toolkit",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Reusable AI agent prompts for development workflows with Jira integration — supports GitHub Copilot, Claude Code, and Codex",
   "author": "Santiago Ramirez",
   "license": "PolyForm-Noncommercial-1.0.0",

package/src/index.js

@@ -3,43 +3,79 @@
  * @module @silverassist/agents-toolkit
  */
 
-export const VERSION = "2.2.0";
+export const VERSION = "2.4.0";
 
 export const PROMPTS = {
   workflow: [
+    "analyze-github-issue",
     "analyze-ticket",
+    "create-github-pr",
     "create-plan",
-    "work-ticket",
-    "prepare-pr",
     "create-pr",
+    "finalize-github-pr",
     "finalize-pr",
+    "prepare-pr",
+    "prepare-release",
+    "work-github-issue",
+    "work-ticket",
+  ],
+  utility: [
+    "add-tests",
+    "audit-ai-seo",
+    "fix-issues",
+    "new-wp-component",
+    "new-wp-plugin",
+    "quality-check",
+    "review-code",
   ],
-  utility: ["review-code", "fix-issues", "add-tests"],
 };
 
 export const PARTIALS = [
-  "validations",
+  "documentation",
   "git-operations",
+  "github-integration",
   "jira-integration",
-  "documentation",
   "pr-template",
+  "validations",
 ];
 
 export const INSTRUCTIONS = [
-  "typescript",
+  "css-styling",
+  "documentation-language",
+  "github-workflow",
+  "php-standards",
   "react-components",
   "server-actions",
+  "testing-standards",
   "tests",
-  "css-styling",
+  "typescript",
+  "wordpress-plugin-architecture",
 ];
 
 export const SKILLS = [
+  "ai-seo-optimization",
   "component-architecture",
+  "create-component",
   "domain-driven-design",
+  "plugin-creation",
+  "quality-checks",
+  "release-management",
+  "testing",
   "testing-patterns",
-  "ai-seo-optimization",
 ];
 
+export const HOOKS = ["validate-tsx", "lint-format"];
+
+// Skills follow the `npx skills` standard: a single canonical copy lives in
+// .agents/skills/ and each agent's skills directory symlinks to it.
+export const SKILLS_LAYOUT = {
+  canonicalDir: ".agents/skills",
+  agentDirs: {
+    claude: ".claude/skills",
+    copilot: ".github/skills",
+  },
+};
+
 // Claude Code equivalents
 export const CLAUDE_COMMANDS = [
   "analyze-ticket",
@@ -56,4 +92,5 @@ export const CLAUDE_COMMANDS = [
 export const CLAUDE_FILES = {
   instructions: "CLAUDE.md",
   commandsDir: ".claude/commands",
+  skillsDir: ".claude/skills",
 };

package/templates/shared/hooks/lint-format.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "scripts/lint-format.sh",
+        "timeout": 30
+      }
+    ]
+  }
+}

package/templates/shared/hooks/scripts/lint-format.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# lint-format.sh — PostToolUse hook for VS Code Copilot
+# Runs eslint --fix and prettier --write on files modified by the agent.
+# This ensures agent-generated code follows project formatting standards.
+# Exit 0 = pass (always), diagnostics printed to stderr.
+
+set -uo pipefail
+
+FILE="${COPILOT_FILE:-}"
+
+if [[ -z "$FILE" ]]; then
+  exit 0
+fi
+
+# Only process TypeScript, JavaScript, and CSS files
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.css) ;;
+  *) exit 0 ;;
+esac
+
+# Resolve to absolute path to prevent infinite loop in directory walk
+if [[ "$FILE" != /* ]]; then
+  FILE="$(cd "$(dirname "$FILE")" && pwd)/$(basename "$FILE")"
+fi
+
+# File must exist
+if [[ ! -f "$FILE" ]]; then
+  exit 0
+fi
+
+# Find project root (look for package.json)
+DIR="$(dirname "$FILE")"
+PROJECT_ROOT=""
+while [[ "$DIR" != "/" ]]; do
+  if [[ -f "$DIR/package.json" ]]; then
+    PROJECT_ROOT="$DIR"
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+  exit 0
+fi
+
+# Resolve tool paths
+ESLINT="$PROJECT_ROOT/node_modules/.bin/eslint"
+PRETTIER="$PROJECT_ROOT/node_modules/.bin/prettier"
+
+# Run ESLint --fix (only on TS/JS files)
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx)
+    if [[ -x "$ESLINT" ]]; then
+      "$ESLINT" --fix "$FILE" || true
+    fi
+    ;;
+esac
+
+# Run Prettier --write
+if [[ -x "$PRETTIER" ]]; then
+  "$PRETTIER" --write "$FILE" || true
+fi
+
+exit 0

package/templates/shared/hooks/scripts/validate-tsx.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# validate-tsx.sh — PostToolUse hook for VS Code Copilot
+# Validates that TSX component files follow project conventions.
+# Exit 0 = pass, Exit 1 = fail (shown as warning to Copilot).
+
+set -euo pipefail
+
+# Only run when a .tsx file was modified
+FILE="${COPILOT_FILE:-}"
+
+if [[ -z "$FILE" ]]; then
+  exit 0
+fi
+
+if [[ "$FILE" != *.tsx ]]; then
+  exit 0
+fi
+
+# Only validate files inside components/ directories
+if [[ "$FILE" != *"/components/"* ]]; then
+  exit 0
+fi
+
+ERRORS=()
+
+# --- Rule 1: Component must be inside a folder with index.tsx ---
+BASENAME=$(basename "$FILE")
+DIRNAME=$(basename "$(dirname "$FILE")")
+
+if [[ "$BASENAME" != "index.tsx" && "$DIRNAME" != "__tests__" ]]; then
+  ERRORS+=("Component files must be named index.tsx inside a kebab-case folder (found: $BASENAME)")
+fi
+
+# --- Rule 2: Parent folder must be kebab-case ---
+if [[ "$BASENAME" == "index.tsx" ]]; then
+  if [[ ! "$DIRNAME" =~ ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ ]]; then
+    ERRORS+=("Component folder must be kebab-case (found: $DIRNAME)")
+  fi
+fi
+
+# --- Rule 3: Must have a default export function (PascalCase) ---
+if [[ "$BASENAME" == "index.tsx" ]] && [[ -f "$FILE" ]]; then
+  if ! grep -qE "^export default function [A-Z]" "$FILE"; then
+    ERRORS+=("Component must use 'export default function PascalName' pattern")
+  fi
+fi
+
+# --- Rule 4: Props interface should exist for non-trivial components ---
+if [[ "$BASENAME" == "index.tsx" ]] && [[ -f "$FILE" ]]; then
+  # Check if there are props being destructured
+  if grep -qE "^export default function [A-Z][a-zA-Z]+\(" "$FILE"; then
+    # If it has props (not empty parens), check for interface
+    if grep -qE "^export default function [A-Z][a-zA-Z]+\(\{" "$FILE"; then
+      if ! grep -qE "^(export )?(interface|type) [A-Z][a-zA-Z]+Props" "$FILE"; then
+        ERRORS+=("Components with props should define a Props interface (e.g., interface ComponentNameProps)")
+      fi
+    fi
+  fi
+fi
+
+# --- Rule 5: No relative imports (must use @/ prefix) ---
+if [[ -f "$FILE" ]]; then
+  if grep -qE "^import .+ from ['\"]\.\.?/" "$FILE" || grep -qE "^import ['\"]\.\.?/" "$FILE"; then
+    ERRORS+=("Relative imports found. Use absolute imports with @/ prefix instead of ./ or ../")
+  fi
+fi
+
+# --- Report ---
+if [[ ${#ERRORS[@]} -gt 0 ]]; then
+  echo "⚠️  TSX validation issues in: $FILE"
+  for err in "${ERRORS[@]}"; do
+    echo "  • $err"
+  done
+  exit 1
+fi
+
+exit 0

package/templates/shared/hooks/validate-tsx.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "scripts/validate-tsx.sh",
+        "timeout": 30
+      }
+    ]
+  }
+}

package/templates/shared/prompts/create-github-pr.prompt.md

@@ -0,0 +1,147 @@
+---
+agent: agent
+description: Create a pull request for the current branch linked to a GitHub issue
+---
+
+# Create GitHub Pull Request
+
+Create a pull request for the current branch linked to GitHub issue **#{issue-number}**.
+
+## Prerequisites
+- Run `prepare-pr` first to ensure code is ready
+- GitHub MCP connection or `gh` CLI required
+- Reference: `.github/prompts/_partials/pr-template.md`
+- Reference: `.github/prompts/_partials/git-operations.md`
+- Reference: `.github/prompts/_partials/github-integration.md`
+
+## Steps
+
+### 1. Verify Current State
+
+```bash
+git branch --show-current
+git status
+```
+
+Verify:
+- Branch follows convention: `feature/{issue-number}-*` or `bugfix/{issue-number}-*`
+- All changes are committed
+- Not on protected branch
+
+### 2. Review Changes
+
+```bash
+BASE_BRANCH=$(node -e "try{const c=require('./.agents-toolkit.json');console.log(c.pr?.targetBranch||c.git?.defaultBranch||'main')}catch{console.log('main')}")
+git diff "$BASE_BRANCH" --name-only
+```
+
+- Reuse `BASE_BRANCH` in all subsequent steps
+- Summarize the changes made
+- Identify breaking changes or migrations
+
+### 3. Read GitHub Issue
+
+Fetch issue **#{issue-number}** details:
+- Get title for PR title
+- Extract acceptance criteria
+- Get any context from comments
+
+```bash
+gh issue view {issue-number} | cat
+```
+
+### 4. Run Final Validations
+
+```bash
+npm run lint --if-present
+npm run type-check --if-present
+if [ -f tsconfig.json ]; then npx tsc --noEmit; fi
+npm run test --if-present
+npm run build --if-present
+```
+
+Fix any issues before proceeding.
+
+### 5. Push Branch
+
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+### 6. Create Pull Request
+
+#### PR Title
+```
+{Issue title}
+```
+
+#### PR Description
+
+Use this template:
+
+```markdown
+## Summary
+Brief description of what this PR accomplishes.
+
+## Related Issue
+Closes #{issue-number}
+
+## Changes Made
+- Change 1: Description
+- Change 2: Description
+- Change 3: Description
+
+## Type of Change
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 💥 Breaking change
+- [ ] 📝 Documentation
+- [ ] 🔧 Refactoring
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+- Describe test cases here
+
+## Screenshots
+(If UI changes, add before/after screenshots)
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Documentation updated
+- [ ] Tests pass locally
+```
+
+#### Create via CLI
+
+```bash
+gh pr create \
+  --title "{Issue title}" \
+  --body "$(cat <<'EOF'
+## Summary
+...
+
+Closes #{issue-number}
+EOF
+)" \
+  --base "$BASE_BRANCH" | cat
+```
+
+#### PR Settings
+- **Source**: Current branch
+- **Target**: `<base-branch>` resolved from `.agents-toolkit.json` (fallback: `main`)
+- **Reviewers**: Based on changed files
+
+### 7. Comment on GitHub Issue
+
+Add a comment linking to the PR:
+
+```bash
+gh issue comment {issue-number} --body "## Pull Request Created
+
+PR: <pr-url>
+Branch: \`$(git branch --show-current)\`
+
+Work in progress. Review requested." | cat
+```

package/templates/shared/prompts/finalize-github-pr.prompt.md

@@ -0,0 +1,129 @@
+---
+agent: agent
+description: Finalize a pull request after approval and prepare for merge
+---
+
+# Finalize GitHub Pull Request
+
+Finalize PR for GitHub issue **#{issue-number}** after approval and prepare for merge.
+
+## Prerequisites
+- PR has been approved
+- GitHub MCP connection or `gh` CLI required
+- Reference: `.github/prompts/_partials/git-operations.md`
+- Reference: `.github/prompts/_partials/validations.md`
+- Reference: `.github/prompts/_partials/github-integration.md`
+
+## Steps
+
+### 1. Verify PR Status
+
+```bash
+gh pr view --json state,reviewDecision,statusCheckRollup | cat
+```
+
+Check:
+- All required approvals in place
+- CI/CD pipeline passed
+- No unresolved review comments
+
+### 2. Address Review Comments
+
+If there are unresolved comments:
+
+```bash
+gh pr view --json reviews,comments | cat
+```
+
+- List each unresolved comment
+- Address feedback
+- Push additional commits if needed
+- Request re-review if changes are significant:
+
+```bash
+gh pr review --request-changes --body "..." | cat
+# or after fixing:
+gh pr review --approve | cat
+```
+
+### 3. Sync with Base Branch
+
+```bash
+BASE_BRANCH=$(node -e "try{const c=require('./.agents-toolkit.json');console.log(c.pr?.targetBranch||c.git?.defaultBranch||'main')}catch{console.log('main')}")
+git fetch origin
+git rebase "origin/${BASE_BRANCH}"
+```
+
+If conflicts:
+1. Resolve each conflict
+2. Stage resolved files: `git add <file>`
+3. Continue rebase: `git rebase --continue`
+
+Push updated branch:
+```bash
+git push --force-with-lease
+```
+
+### 4. Final Validations
+
+Run complete validation suite:
+```bash
+npm run lint --if-present
+npm run type-check --if-present
+if [ -f tsconfig.json ]; then npx tsc --noEmit; fi
+npm run test --if-present
+npm run build --if-present
+```
+
+Verify:
+- No regressions after rebase
+- All tests still pass
+- No new warnings
+
+### 5. Merge Pull Request
+
+**Recommended merge strategy**: Squash merge
+
+```bash
+gh pr merge --squash --delete-branch | cat
+```
+
+**Final commit message format**:
+```
+{Issue title} (#{pr-number})
+
+- Key change 1
+- Key change 2
+- Key change 3
+```
+
+### 6. Post-Merge Tasks
+
+After merge is complete:
+
+```bash
+# Return to base branch and sync
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
+
+# Delete local branch (force if squash-merged)
+git branch -D <branch-name>
+
+# Clean up stale references
+git remote prune origin
+```
+
+### 7. Close GitHub Issue
+
+The issue closes automatically if the PR description contains `Closes #{issue-number}`.
+If not, close manually:
+
+```bash
+gh issue close {issue-number} --comment "Completed in PR #<pr-number>." | cat
+```
+
+### 8. Clean Up
+
+- [ ] Delete temporary planning docs from `docs/` (if applicable)
+- [ ] Ensure final documentation is complete
+- [ ] Verify commit history is clean

package/templates/shared/prompts/work-github-issue.prompt.md

@@ -93,4 +93,4 @@ Report:
 
 - Begin implementation following the plan
 - Use `prepare-pr` when ready for review
-- Use `create-pr` to submit pull request
+- Use `create-github-pr` to submit pull request

package/templates/shared/skills/README.md

@@ -8,18 +8,39 @@ Skills are markdown files with YAML frontmatter that provide domain-specific gui
 
 ## Structure
 
-Each skill lives in its own folder with a `SKILL.md` file:
+Each skill lives in its own folder with a `SKILL.md` file. Following the
+[`npx skills`](https://github.com/vercel-labs/skills) standard, the real files
+are installed **once** into a canonical `.agents/skills/` store, and each agent's
+skills directory contains symlinks to it (single source of truth):
 
 ```
-.github/skills/
+.agents/skills/                       # canonical store (real files)
+├── ai-seo-optimization/
+│   └── SKILL.md
 ├── component-architecture/
 │   └── SKILL.md
+├── create-component/
+│   └── SKILL.md
 ├── domain-driven-design/
 │   └── SKILL.md
+├── plugin-creation/
+│   └── SKILL.md
+├── quality-checks/
+│   └── SKILL.md
+├── release-management/
+│   └── SKILL.md
+├── testing/
+│   └── SKILL.md
 └── testing-patterns/
     └── SKILL.md
+
+.github/skills/   → symlinks to ../../.agents/skills/*   (Copilot, Codex)
+.claude/skills/   → symlinks to ../../.agents/skills/*   (Claude Code, read natively)
 ```
 
+Use `--copy` at install time to materialize real copies instead of symlinks
+(symlinks also fall back to copies automatically on systems that don't support them).
+
 ## Frontmatter Format
 
 ```yaml
@@ -47,7 +68,8 @@ Skills are automatically picked up by agents when relevant to your question. You
 
 ## Creating Custom Skills
 
-1. Create a folder: `.github/skills/your-skill-name/`
+1. Create a folder: `.agents/skills/your-skill-name/` (canonical store)
 2. Create `SKILL.md` with frontmatter
+3. Run `npx @silverassist/agents-toolkit install --skills-only` to symlink it into `.github/skills/` and `.claude/skills/`
 3. Document patterns, examples, and conventions
 4. Include ✅ CORRECT and ❌ INCORRECT examples