@silverassist/agents-toolkit 2.2.0 → 2.4.0

package/README.md

@@ -14,6 +14,7 @@ Reusable AI agent prompts for development workflows — supports **GitHub Copilo
 - ✅ **Global Install**: Install once for all projects with `--global`
 - ✅ **Modular Partials**: Reusable prompt fragments
 - ✅ **Customizable**: Easy to extend and modify
+- ✅ **PostToolUse Hooks**: Automated validation and formatting after Copilot edits
 - ✅ **CLI Tool**: Quick installation in any project
 
 ## Installation
@@ -63,19 +64,24 @@ AGENTS.md                             # Copilot Coding Agent instructions (proje
 │   ├── analyze-ticket.prompt.md
 │   ├── create-plan.prompt.md
 │   ├── work-ticket.prompt.md
-│   └── ...
+│   └── ...                           # 10 prompts total (depends on --tracker)
 ├── instructions/
 │   ├── typescript.instructions.md
 │   ├── react-components.instructions.md
-│   ├── server-actions.instructions.md
-│   ├── tests.instructions.md
-│   └── css-styling.instructions.md
-└── skills/
-    ├── component-architecture/
+│   └── ...                           # filtered by --stack
+└── skills/                           # Symlinks → ../../.agents/skills/ (npx skills standard)
+    ├── domain-driven-design   -> ../../.agents/skills/domain-driven-design
+    ├── testing-patterns       -> ../../.agents/skills/testing-patterns
+    └── ...                           # filtered by --stack
+.agents/
+└── skills/                           # Canonical store (single source of truth)
     ├── domain-driven-design/
-    └── testing-patterns/
+    ├── testing-patterns/
+    └── ...                           # 9 skills total, filtered by --stack
 ```
 
+> **Skills follow the [`npx skills`](https://github.com/vercel-labs/skills) standard.** The real skill files live once in the canonical `.agents/skills/` store, and each agent's `skills/` directory contains symlinks to it — a single source of truth shared across Copilot, Claude Code, and Codex. Use `--copy` to materialize real copies instead of symlinks (e.g. on Windows without developer mode; symlinks also fall back to copies automatically when unsupported).
+
 **Running prompts in VS Code:**
 
 1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
@@ -95,26 +101,37 @@ This creates the following structure:
 
 ```
 CLAUDE.md                             # Project instructions for Claude Code (project root)
+.agents/
+└── skills/                           # Canonical skills store (single source of truth)
+    ├── domain-driven-design/
+    ├── testing-patterns/
+    └── ...                           # 9 skills total, filtered by --stack
 .claude/
-└── commands/
-    ├── _partials/
-    ├── analyze-ticket.md
-    ├── create-plan.md
-    ├── work-ticket.md
-    └── ...
+├── commands/
+│   ├── _partials/
+│   ├── analyze-ticket.md
+│   ├── create-plan.md
+│   ├── work-ticket.md
+│   └── ...                           # 10 commands total (depends on --tracker)
+└── skills/                           # Symlinks → ../../.agents/skills/ (read natively by Claude Code)
+    ├── domain-driven-design   -> ../../.agents/skills/domain-driven-design
+    ├── testing-patterns       -> ../../.agents/skills/testing-patterns
+    └── ...                           # filtered by --stack
 .github/
-├── instructions/                     # Shared with Copilot
-└── skills/                           # Shared with Copilot
+└── instructions/                     # Shared with Copilot
 ```
 
+> Skills now install to `.claude/skills/` (where Claude Code reads them natively) as symlinks to the canonical `.agents/skills/` store — no longer to `.github/skills/`.
+
 **Running commands in Claude Code:**
 
 Type `/` in the chat to see all available slash commands:
 
 ```
-/analyze-ticket
-/work-ticket
-/create-pr
+/analyze-github-issue
+/work-github-issue
+/create-github-pr
+/finalize-github-pr
 ```
 
 ### Codex
@@ -135,17 +152,20 @@ AGENTS.md                             # Project instructions for Codex (project
 │   ├── analyze-ticket.prompt.md
 │   ├── create-plan.prompt.md
 │   ├── work-ticket.prompt.md
-│   └── ...
+│   └── ...                           # 10 prompts total (depends on --tracker)
 ├── instructions/
 │   ├── typescript.instructions.md
 │   ├── react-components.instructions.md
-│   ├── server-actions.instructions.md
-│   ├── tests.instructions.md
-│   └── css-styling.instructions.md
-└── skills/
-    ├── component-architecture/
+│   └── ...                           # filtered by --stack
+└── skills/                           # Symlinks → ../../.agents/skills/ (npx skills standard)
+    ├── domain-driven-design   -> ../../.agents/skills/domain-driven-design
+    ├── testing-patterns       -> ../../.agents/skills/testing-patterns
+    └── ...                           # filtered by --stack
+.agents/
+└── skills/                           # Canonical store (single source of truth)
     ├── domain-driven-design/
-    └── testing-patterns/
+    ├── testing-patterns/
+    └── ...                           # 9 skills total, filtered by --stack
 ```
 
 ### Global Install (Optional)
@@ -207,8 +227,10 @@ The same set of prompts is available for all supported tools.
 | `work-ticket` | Start working on a Jira ticket | `{ticket-id}` | Jira |
 | `work-github-issue` | Start working on a GitHub issue | `{issue-number}` | GitHub |
 | `prepare-pr` | Prepare code for PR | — | All |
-| `create-pr` | Create a pull request | `{ticket-id}` | Jira |
-| `finalize-pr` | Finalize and merge PR | `{ticket-id}` | Jira |
+| `create-pr` | Create a pull request (Jira) | `{ticket-id}` | Jira |
+| `create-github-pr` | Create a pull request (GitHub) | `{issue-number}` | GitHub |
+| `finalize-pr` | Finalize and merge PR (Jira) | `{ticket-id}` | Jira |
+| `finalize-github-pr` | Finalize and merge PR (GitHub) | `{issue-number}` | GitHub |
 
 ### Utility
 
@@ -220,6 +242,8 @@ The same set of prompts is available for all supported tools.
 
 ### Workflow Stages
 
+**Jira workflow:**
+
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
 │  1. Analyze     │────▶│  2. Plan        │────▶│  3. Work        │
@@ -233,6 +257,21 @@ The same set of prompts is available for all supported tools.
 └─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
+**GitHub workflow:**
+
+```
+┌──────────────────────┐     ┌─────────────────┐     ┌──────────────────────┐
+│  1. Analyze          │────▶│  2. Plan        │────▶│  3. Work             │
+│  analyze-github-issue│     │  create-plan    │     │  work-github-issue   │
+└──────────────────────┘     └─────────────────┘     └──────────────────────┘
+                                                               │
+                                                               ▼
+┌──────────────────────┐     ┌──────────────────────┐  ┌─────────────────┐
+│  6. Finalize         │◀────│  5. Create PR         │◀─│  4. Prepare     │
+│  finalize-github-pr  │     │  create-github-pr     │  │  prepare-pr     │
+└──────────────────────┘     └──────────────────────┘  └─────────────────┘
+```
+
 ## CLI Reference
 
 ### install
@@ -257,6 +296,8 @@ npx @silverassist/agents-toolkit@latest install [options]
 | `--instructions-only` | Only install instructions and instructions file |
 | `--partials-only` | Only install partials |
 | `--skills-only` | Only install skills |
+| `--hooks-only` | Only install hooks (PostToolUse validation scripts) |
+| `--copy` | Copy skills into each agent dir instead of symlinking to `.agents/skills/` |
 | `--dry-run` | Show what would be installed without making changes |
 
 **Examples:**
@@ -306,7 +347,7 @@ npx @silverassist/agents-toolkit@latest update --global
 
 ### update
 
-Update all prompts to the latest version. **Overwrites existing files** (equivalent to `install --force`).
+Update all prompts to the latest version. **Overwrites existing files and refreshes the skills lockfile** (equivalent to `install --force`).
 
 ```bash
 npx @silverassist/agents-toolkit@latest update [options]
@@ -316,6 +357,28 @@ npx @silverassist/agents-toolkit@latest update --codex
 
 > ⚠️ **Warning:** This will replace any customizations you've made to the installed files.
 
+### restore
+
+Restore skills from the lockfile. Reads `agents-toolkit-lock.json` and reinstalls all skills with the correct symlinks. Designed for post-clone setup and CI pipelines.
+
+```bash
+npx @silverassist/agents-toolkit@latest restore
+npx @silverassist/agents-toolkit@latest restore --force   # overwrite existing files
+npx @silverassist/agents-toolkit@latest restore --dry-run # preview only
+```
+
+> If the lockfile was written by a different package version, `restore` warns but still proceeds.
+
+### status
+
+Check whether installed skills match the lockfile. Useful in CI to detect drift (manually edited skills or stale installs).
+
+```bash
+npx @silverassist/agents-toolkit@latest status
+```
+
+Exits with code `0` if all skills are up-to-date, `1` if any skill is `missing` or `modified`.
+
 ### list
 
 List all available prompts and skills.
@@ -338,6 +401,8 @@ npx @silverassist/agents-toolkit@latest list
 | Get latest version (discard customizations) | `update` |
 | Update specific category only | `update --prompts-only` |
 | Preview what would change | `install --dry-run` |
+| Restore skills after clone / CI | `restore` |
+| Check if skills are in sync | `status` |
 
 ## Partials
 
@@ -374,15 +439,88 @@ Specialized knowledge guides for domain-specific patterns:
 | `domain-driven-design` | DDD principles, domain organization, barrel exports |
 | `testing-patterns` | Jest + RTL patterns for Next.js 15 and Server Actions |
 
-**GitHub Copilot** — reference a skill explicitly:
+Skills follow the [`npx skills`](https://github.com/vercel-labs/skills) standard: the real files live once in the canonical `.agents/skills/` store, and each agent's `skills/` directory symlinks to it (single source of truth, easy updates). Pass `--copy` to materialize real copies instead.
+
+**GitHub Copilot** — skills are symlinked into `.github/skills/`. Reference a skill explicitly:
 
 ```
 @workspace Use the component-architecture skill to create a new payment form
 ```
 
-**Claude Code** — skills are stored in `.github/skills/` and can be referenced in any prompt or command.
+**Claude Code** — skills are symlinked into `.claude/skills/`, where Claude Code reads them natively, and can be referenced in any prompt or command.
+
+**Codex** — skills are symlinked into `.github/skills/` and can be referenced from `AGENTS.md` and task context.
+
+### Skills Lockfile
+
+When skills are installed, an `agents-toolkit-lock.json` file is written to the project root. This lockfile records each installed skill with its SHA-256 hash (same algorithm used by `npx skills`), allowing teammates and CI pipelines to restore the exact same skill files without committing them to the repository.
+
+**Recommended `.gitignore` entries** (automatically appended by `install`):
+
+```gitignore
+# agents-toolkit managed — regenerate with: npx @silverassist/agents-toolkit restore
+.agents/skills/
+.github/skills/
+.claude/skills/
+```
+
+**Workflow:**
 
-**Codex** — skills are stored in `.github/skills/` and can be referenced from `AGENTS.md` and task context.
+```bash
+# Developer A — installs and commits only the lockfile
+npx @silverassist/agents-toolkit@latest install
+git add agents-toolkit-lock.json
+git commit -m "chore: add agents-toolkit skills"
+
+# Developer B / CI — after cloning, restores skills from the lockfile
+npx @silverassist/agents-toolkit@latest restore
+
+# Check sync status in CI
+npx @silverassist/agents-toolkit@latest status   # exits 1 if any skill is missing/modified
+
+# Update skills to latest package version
+npx @silverassist/agents-toolkit@latest update   # rewrites lockfile with new hashes
+```
+
+## Hooks
+
+PostToolUse hooks run automatically after GitHub Copilot edits files. They provide real-time validation and formatting without manual intervention.
+
+| Hook | Trigger | Description |
+|------|---------|-------------|
+| `validate-tsx` | `*.tsx` in `components/` | Validates kebab-case folders, `index.tsx` naming, default export, and Props interface |
+| `lint-format` | `*.ts, *.tsx, *.js, *.jsx, *.css` | Runs ESLint `--fix` and Prettier `--write` on the modified file |
+
+Hooks are installed to:
+
+- **Project** (default): `.github/hooks/`
+- **Global** (`--global`): `~/.copilot/hooks/`
+
+```
+.github/hooks/              # or ~/.copilot/hooks/ for global
+├── validate-tsx.json       # Hook config (PostToolUse trigger)
+├── lint-format.json        # Hook config (PostToolUse trigger)
+└── scripts/
+    ├── validate-tsx.sh     # Validation logic (exit 1 = warning)
+    └── lint-format.sh      # Auto-fix logic (always exit 0)
+```
+
+Install only hooks:
+
+```bash
+# Project-level (hooks apply to this project only)
+npx @silverassist/agents-toolkit@latest install --hooks-only
+
+# Global (hooks apply to all Copilot sessions)
+npx @silverassist/agents-toolkit@latest install --hooks-only --global
+```
+
+> **How hook paths resolve.** Copilot runs a hook `command` from the workspace root, not
+> the hooks directory. Each generated config therefore sets a `cwd` so `scripts/<name>.sh`
+> resolves: `.github/hooks` (relative, portable) for project installs and the absolute hooks
+> path for global installs. Configs also declare the required `version: 1` field. If you
+> installed hooks with an older version and see `scripts/<name>.sh: No such file or directory`,
+> re-run the install with `--force` to regenerate the configs.
 
 ## Agent Instructions Files
 
@@ -405,12 +543,36 @@ Installed at the project root with `--claude`. Contains project-wide instruction
 
 - Node.js 18+
 - Git installed and configured
-- **For Jira tracker:** Atlassian MCP configured
-- **For GitHub tracker:** GitHub MCP configured
+- **For Jira tracker:** Atlassian MCP configured (see below)
+- **For GitHub tracker:** GitHub MCP configured (see below)
 - **For GitHub Copilot:** VS Code with GitHub Copilot extension
 - **For Claude Code:** Claude Code CLI or VS Code extension
 - **For Codex:** Codex CLI/session running at project root
 
+### MCP Server Configuration
+
+The Jira and GitHub workflow prompts rely on MCP servers to read/write tickets and pull requests.
+Add a `.mcp.json` file to your project root (or use VS Code's MCP settings) to register the servers:
+
+```json
+{
+  "servers": {
+    "atlassian": {
+      "type": "http",
+      "url": "https://mcp.atlassian.com/v1/mcp"
+    },
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
+    }
+  }
+}
+```
+
+> You only need to include the server(s) matching your `--tracker` choice.
+> The Atlassian MCP uses OAuth — authenticate once with `npx @atlassian/mcp-server auth` or via the VS Code MCP UI.
+> The GitHub MCP is authenticated automatically when you are signed in to GitHub Copilot.
+
 ## License
 
 [PolyForm Noncommercial License 1.0.0](https://github.com/SilverAssist/agents-toolkit/blob/main/LICENSE)