Project Notes

This file is the developer-handoff for AI assistants working in this repository. It is not specific to any single runtime — the marketplace ships plugins for Claude Code, Cursor, and OpenCode from a single source tree, and the installer (npx devkit-ai) translates per-target.

Project Overview

A multi-runtime plugin marketplace containing three plugins: typescript-rules, jsdoc-standards, and commit-commands. The marketplace ships an npx devkit-ai installer that copies the plugins into Claude Code, Cursor, or OpenCode at any of three scopes (project, project-local, user). The marketplace is being extended so all three runtimes get the same skill / command / hook surface.

The repo is mostly markdown, JSON configs, shell scripts, and a static HTML landing page — but there is also a Node-based installer (bin/install.mjs + src/installer/*.mjs, ESM, one runtime dep: @clack/prompts). The build step for the landing page is a single bash script.

Repository Structure

• .claude-plugin/marketplace.json — Marketplace manifest declaring all three plugins. The .claude-plugin/ directory is Claude Code's conventional manifest path; the installer's source-of-truth is the JSON inside it, not the directory name.
• plugins/typescript-rules/ — TypeScript conventions plugin (agent, command, skill, hooks)
• plugins/jsdoc-standards/ — JSDoc documentation plugin (agent, command, skill, hooks)
• plugins/commit-commands/ — Git workflow plugin (commands, agents, skill; no hooks)
• .cursor/skills/ — Cursor-readable symlinks to each plugin's skills (generated by the build script)
• package.json + bin/install.mjs + src/installer/*.mjs — devkit-ai npm package, an @clack/prompts-based installer that copies the plugins into Claude Code, Cursor, or OpenCode at any of three scopes
• marketplace.html — Static landing page rendered to GitHub Pages, embeds plugin metadata via const PLUGINS = [...]
• scripts/build-marketplace.sh — Discovers components in each plugin, generates .cursor/skills/ symlinks, and injects fresh JSON into marketplace.html
• .github/workflows/deploy-pages.yml — Runs the build script and deploys marketplace.html to Pages on every push
• .github/workflows/release-please.yml — Release-please + npm publish to the public npm registry

Each plugin follows the standard layout:

plugins/<plugin>/
  .claude-plugin/plugin.json
  agents/*.md           (optional)
  commands/*.md         (optional)
  hooks/hooks.json      (optional, with hooks/scripts/*.sh)
  skills/<name>/SKILL.md (optional, with skills/<name>/references/*.md)

How to Test Locally

The marketplace is a collection of plugins, not a single plugin — there is no Devkit-AI plugin to load directly. Two options:

Test the marketplace via Claude Code:

/plugin marketplace add /absolute/path/to/this/repo
/plugin install typescript-rules@pau-vega-Devkit-AI

Then run /reload-plugins to load without restarting.

Test the installer locally:

node bin/install.mjs --dry-run   # print what would be written
node bin/install.mjs --version    # print the package version
node bin/install.mjs --help       # print usage

To exercise the OpenCode target specifically, run the installer with opencode selected and inspect .opencode/agents/<name>.md — the model: sonnet line should be absent and mode: subagent should be present.

Regenerate the landing page after changing plugin metadata or components:

bash scripts/build-marketplace.sh

There are no lint or test commands. Validation is done by loading the plugin in Claude Code and exercising the hooks, command, and agent, or by running the installer against a scratch directory.

Architecture

The convention plugins (typescript-rules, jsdoc-standards) enforce their rules through three layers (commit-commands is workflow-only: commands + agents + a skill, no hooks):

1. Hooks (real-time) — <plugin>/hooks/hooks.json registers PreToolUse hooks that fire on Bash, Write, and Edit tool calls. Shell scripts do pattern matching (e.g., grep for any, enum). Prompt-based hooks validate proposed code via the assistant. Available for Claude Code (and Cursor, with a different schema); OpenCode does not consume hooks.json.
2. Command + Agent (on-demand) — <plugin>/commands/*.md dispatches an agent that loads the conventions skill, discovers target files, and produces a structured report with Error/Warning/Suggestion severity levels. Available for Claude Code and OpenCode; Cursor has no portable agent format.
3. Skill (reference) — Passive skills that the assistant consults when writing or reviewing code in any project that has the plugin installed.

The installer (bin/install.mjs) layers a fourth axis on top: per-runtime target-root resolution in src/installer/targets.mjs (Claude Code, Cursor, OpenCode × project, project-local, user), @clack/prompts-driven flow in src/installer/prompts.mjs, per-file conflict handling in src/installer/conflicts.mjs, per-target content translation in src/installer/translator.mjs, and src/installer/gitignore.mjs for the project-local delimited block in .gitignore. Cursor agents and OpenCode hooks are documented skip rules — see the README's "Known limitations" section.

Key Conventions When Editing This Plugin

• Hook scripts read tool input from stdin as JSON (INPUT=$(cat)) and use jq to extract fields.
• Hook scripts block by printing a reason to stderr and exiting with code 2, or exit 0 silently to allow.
• Prompt-based hooks (inline "type": "prompt" in hooks.json) validate file content against rules and respond with approve or deny.
• ${CLAUDE_PLUGIN_ROOT} is the variable Claude Code injects in hooks.json and agent files to reference the plugin's root directory. OpenCode has no equivalent — src/installer/translator.mjs rewrites body references to relative .. paths at install time.
• Agent model: sonnet is Claude Code's default. OpenCode's model field requires a provider-qualified ID, so the translator drops the line for OpenCode targets; the agent then inherits the user's opencode.json model (any provider).
• Agents use model: sonnet (Claude Code format) and have access to Read, Glob, Grep, and Bash tools only.
• Slash commands dispatching subagents use allowed-tools: [Agent] (the canonical Claude Code subagent tool name).
• Command hooks honor a per-project settings file (.claude/<plugin>.local.md, YAML frontmatter) read at invocation time by hooks/scripts/settings-lib.sh (one copy per hook-bearing plugin, kept identical). enabled: false disables all of a plugin's command hooks; <rule_key>: false disables one rule. Missing file or key means enabled. The prompt-based hook in typescript-rules cannot read project files and ignores the settings file.
• Installer source files are ESM .mjs and import with explicit .mjs extensions; the package has "type": "module". The sole runtime dep is @clack/prompts — do not add others without a reason.
• After editing marketplace.json or any plugin component, run scripts/build-marketplace.sh to refresh marketplace.html.
• The top-level version field and every plugin's version field in .claude-plugin/marketplace.json, plus each plugin's .claude-plugin/plugin.json version, are bumped automatically by release-please on every release, in lockstep with package.json. See the extra-files config in .github/release-please-config.json.

Design Context

Users

Developers curious about or adopting AI coding assistants — Claude Code, Cursor, or OpenCode — who stumble on this marketplace via GitHub, a blog post, or a referral. They arrive already technical: they understand what agents, hooks, and skills are. The job to be done is quick evaluation: "Is this plugin worth installing?" The interface should answer that question with minimal friction, then get out of the way.

Brand Personality

Calm and trustworthy. This is a personal portfolio that signals craft and reliability — not a flashy product page. Voice is direct and precise. The work earns trust through consistency, not persuasion.

Three words: reliable, precise, unassuming

Aesthetic Direction

• Warm dark neutrals as the foundation — #0f0e0c background, not cool steel gray. The warmth signals care, not just efficiency.
• Violet accent (#7c6aef) for interactive elements — distinct without being aggressive.
• Space Grotesk for headings (technical yet slightly geometric), system UI for body, monospace for code.
• Minimal cards — no border at rest, border reveals on hover/focus. Visual noise only earns its place on interaction.
• Light mode is a first-class alternative (not an afterthought), using [data-theme="light"] CSS variables.
• Anti-references: no heavy glows, no gradients on cards, no external decorative imagery, no overstyled hero sections.

Design Principles

1. Let the content lead. The plugins are the point. The UI frames and clarifies — it never competes.
2. Earn every pixel. If an element doesn't carry information or guide interaction, remove it. Restraint is a feature.
3. Consistent over clever. Predictable spacing, transition timing, and color usage build the sense of a well-maintained tool.
4. Accessible by default. Target WCAG 2.1 AA. Focus rings, ARIA roles, reduced motion, and sufficient contrast are not optional.
5. Warm, not sterile. Prefer warm neutrals over cool grays. The palette should feel hand-picked, not auto-generated.