skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-12 22:26:38 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
1268f10b76705fa21f8e1ad8a9e412d1534adefc
pbakaus_impeccable/docs/HARNESSES.md
T
Abdul WahabGitHubCursor
 672517f76e Add automatic design hook install and exceptions (#170) 
* docs: add PRD for design detector hook integration

Plans a PostToolUse hook for Claude Code and Codex that runs the
existing design detector after every relevant file write and feeds
findings back to the agent as advisory system-reminder context. No
implementation in this commit; covers UX, technical design, build
pipeline changes, distribution, coverage tradeoffs, and rollout.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs: revise hook PRD with best-practices review

Folds in the P0/P1/P2 findings from an online best-practices critique
against the official Claude Code and Codex hook references plus 10+
2026 community guides and similar prior-art tools (claw-hooks,
claude-code-hooks-mastery).

Key changes:
- Exec form everywhere (Codex snippet was shell form), with Windows
  rationale.
- Default timeout dropped from 10s to 5s.
- Re-entrancy guard (CLAUDE_HOOK_DEPTH) and per-file edit counter.
- Session-scoped finding dedup promoted from open question to v1.
- Per-language inline-ignore syntax map (HTML/JSX/CSS/JS).
- Hard-skip rules for sensitive paths and generated/lock files.
- Honest framing about Claude Code lacking per-plugin hook disable.
- Honest framing about Bash-written files being invisible in v1.
- Codex Windows-not-supported call-out, feature flag note, trust ceremony detail.
- Optional NDJSON audit log via IMPECCABLE_HOOK_LOG.
- Findings cap lowered 8 → 5 with attention-budget rationale.
- Versioned envelope ([impeccable@1]) on rendered template.
- Expanded test plan, decision log, and stdin payload appendix.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(hooks): ship the design detector hook for Claude Code and Codex

Implements docs/hooks-prd.md: a PostToolUse hook that runs the
impeccable design detector after every Edit/Write/MultiEdit on a UI
file and pushes findings into the agent's next-turn context as a
short system reminder. Silent on clean files. Never blocks an edit.

Why this matters: today, design slop (side-tab borders, gradient
text, purple/cyan palettes, bounce easing, etc.) only gets caught
when a human notices or someone explicitly runs /impeccable audit.
The hook closes the loop at the moment slop is written.

What ships in v1
- skill/scripts/hook.mjs: PostToolUse entry. Reads stdin, runs the
  detector in-process (no `npx impeccable` cold start), emits
  hookSpecificOutput.additionalContext when fresh findings exist.
- skill/scripts/hook-lib.mjs: extracted helpers (config, cache,
  filter, render, audit log, runHook orchestrator). 100% unit-testable.
- skill/scripts/hook-session-start.mjs: SessionStart greeting,
  gated by a project-scannable probe + 30-day throttle.
- skill/scripts/hook-admin.mjs: backs /impeccable hooks
  on/off/status/ignore-rule/ignore-file/reset.

Hardening built in
- Re-entrancy guard (IMPECCABLE_HOOK_DEPTH) so the hook can never
  recursively spawn itself.
- Hard-skip regexes for sensitive paths (.env, .pem, id_rsa,
  secrets, credentials, .git) and generated/lock/build output. These
  fire before the file is even read; cannot be turned off via config.
- Path-traversal check on the inbound file_path.
- Session-scoped dedup keyed by (session, file, rule, line) so the
  same finding never lands in context twice. Prevents the ~12.5K
  wasted tokens per chatty session called out in the PRD.
- Per-(session, file) edit counter with a one-shot suppression
  notice on the 7th edit, silent after.
- Fail-open contract: every error path returns exit 0 with no
  stdout. Optional NDJSON audit log via IMPECCABLE_HOOK_LOG.

Three kill switches (precedence high to low):
1. IMPECCABLE_HOOK_DISABLED env var (1/true/yes/on, case-insensitive)
2. .impeccable/hook.json `enabled: false`
3. /impeccable hooks off slash command (writes the JSON)

Inline ignores are language-aware. `// impeccable: ignore <rule>` for
JS/TS, `<!-- impeccable: ignore <rule> -->` for HTML/Vue/Svelte/Astro,
`{/* impeccable: ignore <rule> */}` for JSX/TSX, `/* impeccable:
ignore <rule> */` for CSS. `*` matches any rule. Directive applies
to the next non-blank line. Same shape as ESLint, Stylelint, Biome.

Build pipeline
- scripts/lib/transformers/hooks.js: per-provider hooks.json
  builders, plus the slim .codex-plugin/plugin.json manifest.
- providers.js: emitHooks: 'claude' for claude-code, emitHooks:
  'codex' for codex and agents. Codex also emits emitCodexPlugin.
- factory.js: emits hooks/hooks.json next to the skills tree.
- build.js: syncs hooks/ into harness roots and into the slim
  plugin/ subtree; writes .codex-plugin/plugin.json. Build is
  idempotent (verified: 98 staged files unchanged across two runs).

Claude Code wiring uses exec form (command + args) and the
${CLAUDE_PLUGIN_ROOT} placeholder. Matcher: Edit|Write|MultiEdit.
`if:` glob filters to UI extensions before spawning Node. PostToolUse
timeout 5s, SessionStart timeout 3s.

Codex wiring uses ${PLUGIN_ROOT} (Codex's native placeholder),
matcher Edit|Write|apply_patch, no `if:` analog (the script does the
extension filter). macOS and Linux only; hooks are disabled on
Windows in current Codex builds. The trust ceremony and feature flag
are documented in README.md.

Routing
- /impeccable hooks lives outside the 23-command router table on
  purpose: it is plumbing, not a design skill. The hidden
  routing slot is added to SKILL.md alongside pin/unpin so the LLM
  knows to dispatch it. The 23-command count and all stale-count
  validators remain happy.

Tests
- tests/hook.test.mjs: 38 unit tests covering env parsing, config
  load + defaults + malformed, cache round-trip + GC,
  ignoreRules/minSeverity/inline ignores (all four languages),
  globbing with **/*/{a,b}, render template with cap + clamp + 0-line
  prefix drop, audit log NDJSON, payload event-name parameterization,
  re-entrancy, kill switches, sensitive-path + generated-path +
  traversal skips, allowlist filter, config ignoreFiles, edit
  counter cycle including the 7th-edit notice, MultiEdit and
  apply_patch payload shapes, detector throw swallow, malformed
  stdin, missing file race.
- tests/hook-build.test.mjs: 18 integration tests covering hook
  manifest shape (matcher, timeouts, exec form, if: glob, placeholders),
  Codex differences (${PLUGIN_ROOT}, no if:, no SessionStart),
  Codex plugin manifest (no inline hooks field to avoid the
  duplicate-file error), routing across the hooksJsonFor table, and
  presence of all three committed artifacts plus the bundled detector
  the runtime relative-import path depends on.

Full suite: 175 bun tests + 186 node tests, all green.

Docs
- README.md: new "Design hook" section explaining default behavior,
  per-project / global / inline disable paths, the JSON schema knobs,
  the audit log debug flag, and the slop / a11y coverage split.
- HARNESSES.md: flips the `hooks` row for Codex from No -> Yes
  (Claude was already Yes), adds a per-harness hook-surface table
  with the manifest location and matcher each provider uses.

Open questions from the PRD intentionally deferred to v2: Bash-write
blind spot, effort-aware suppression, Stop-hook session summary,
per-rule severity, async hook mode. None block v1.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix Codex hook scanning: apply_patch paths and co-located stylesheets

Parse file targets from Codex apply_patch command bodies, co-scan imported
and sibling CSS when UI components are edited, drop the git-sweep PostToolUse
group, and align Codex SessionStart manifest and trust docs with the official
hooks spec.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Gitignore hook session cache and drop local test HTML

Hook dedup/throttle state in .impeccable/hook.cache.json is per-project
runtime data like other .impeccable/ sidecars. Remove an untracked
bad-nested-flexbox scratch page from site/public/.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix Claude Code hook: drop Edit-only if filter so Write/MultiEdit fire

Claude's if permission rule binds to one tool name, so Edit(*.{…}) never
spawned the hook on Write or MultiEdit despite the matcher listing them.
Extension filtering now lives in hook-lib on both Claude and Codex.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Surface Cursor design findings via stop-hook followup

Replace dropped postToolUse additional_context with afterFileEdit recording
and a one-shot stop followup_message so anti-pattern nudges reach the agent.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix design hook packaging and scans

* Fix Cursor hook pending bucket fallback

* Fix Sass hook scan coverage

* Fix Cursor hook review findings

* Fix session start dead hook normalization

* Fix hook config and relative scan paths

* Remove SessionStart design hook

* Remove redundant afterFileEdit normalization

* Fix Cursor suppression and module style scans

* Fix sensitive path hook filter

* Fix disabled Cursor stop hook emission

* Refresh hook harness artifacts

* Fix Cursor hook manifest install

* Add hook ignore-value support

* Ignore hook runtime files locally

* Fix Codex plugin hook packaging

* fix: address PR review bot findings

Block numeric hook depth counters from re-entering.

Avoid following stylesheet imports from traversal-looking hook targets.

* fix: gate ignore-value suggestions by supported rules

Only render exact ignore-value commands when the same finding can be suppressed by ignoreValues.

* Package Codex plugin as hook-only

* Remove Codex plugin packaging

* Recover hook install probe plumbing

* Remove Codex hook packaging follow-up doc

* Remove extra hook docs and skill wording changes

* Install real design hooks via skills CLI

* Add provider hook smoke runner

* Fix Cursor hook delivery with preToolUse gate

* Simplify Cursor hook install to preToolUse

* Clarify confirmed hook exceptions

* Persist hook ignores in shared config

* Guard font hook exceptions

* Fix hook install after main rebase

* Fix hook scan target handling

* fix: address hook review findings

* Address hook review feedback

* Stabilize DeepSeek insert live fixture

* Fix Cursor hook Python shell write bypass

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-13 21:19:19 -07:00

6.9 KiB
Raw Blame History

Harness Skills Capabilities Reference

Source of truth for what each AI coding harness supports in terms of agent skills. Used to inform provider configs in scripts/lib/transformers/providers.js.

Last verified: 2026-04-28

Official Documentation

Harness Docs URL
Claude Code https://code.claude.com/docs/en/skills
Cursor https://cursor.com/docs/context/skills
Gemini CLI https://geminicli.com/docs/cli/skills/
Codex CLI https://developers.openai.com/codex/skills
GitHub Copilot (Agents) https://code.visualstudio.com/docs/copilot/customization/agent-skills
Kiro https://kiro.dev/docs/skills/
OpenCode https://opencode.ai/docs/skills/
Pi https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md
Qoder https://docs.qoder.com/extensions/skills
Trae TBD (no official skills docs found yet)
Rovo Dev https://support.atlassian.com/rovo/docs/extend-rovo-dev-cli-with-agent-skills

Spec Compliance

All harnesses follow the Agent Skills specification to varying degrees. The spec defines these frontmatter fields: name, description, license, compatibility, metadata, allowed-tools.

Provider-specific extensions beyond the spec: user-invocable, argument-hint, disable-model-invocation, allowed-tools (extended syntax), model, effort, context, agent, hooks, subtask, mcp.

Frontmatter Support

Fields marked with * are spec-standard. Others are provider extensions.

Field Claude Code Cursor Gemini Codex Copilot Kiro OpenCode Pi Qoder Rovo Dev
name* Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
description* Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
license* Yes Yes Ignored No Yes Yes Yes Yes Yes Yes
compatibility* Yes Yes Ignored No Yes Yes Yes Yes Yes Yes
metadata* Yes Yes Ignored No Yes Yes Yes Yes Yes Yes
allowed-tools* Yes No Ignored No No No Yes Yes Yes Yes
user-invocable Yes No No No Yes No Yes No Yes Yes
argument-hint Yes No No No Yes No Yes No Yes Yes
disable-model-invocation Yes Yes No No Yes No Yes Yes TBD TBD
model Yes No No No No No Yes No No No
effort Yes No No No No No No No No No
context Yes No No No No No No No No No
agent Yes No No No No No Yes No No No
hooks Yes No No Yes No No No No No No

Notes:

  • Gemini CLI validates only name and description; other spec fields are parsed but ignored.
  • Codex CLI uses a separate agents/openai.yaml sidecar for skill metadata (icons, branding, MCP tools, invocation control). Codex also auto-discovers subagents bundled inside an installed skill's agents/ folder (TOML), which is how Impeccable ships its asset-producer. Standalone custom agents can still live under .codex/agents/ or ~/.codex/agents/, but Impeccable no longer installs anything there.
  • Codex CLI hooks ship under [features].hooks = true (still flagged), require /hooks trust ceremony per-update, and are disabled on Windows.
  • Kiro recognizes user-invocable and disable-model-invocation per community reports but does not formally document them.
  • Unknown fields are silently ignored by all harnesses.

Hook surface used by Impeccable

Harness Edit hook Startup hook Manifest location Notes
Claude Code Yes (PostToolUse) No .claude/settings.json Project-local settings entry installed by npx impeccable skills install/update. Runs .claude/skills/impeccable/scripts/hook.mjs.
Codex CLI Yes (PostToolUse) No .codex/hooks.json Project-local manifest installed with the .agents/skills/impeccable payload. Runs .agents/skills/impeccable/scripts/hook.mjs from the git root. Requires normal /hooks trust approval.
Cursor Yes (preToolUse) No .cursor/hooks.json Project-level manifest installed with .cursor/skills/impeccable. Runs hook-before-edit.mjs to block bad proposed writes before they land. Reloads on save; restart Cursor if hooks do not pick up.
All other harnesses No No n/a No documented hook surface today. Skill and commands still ship.

Skill Directory Structure

Harness Native directory Also reads
Claude Code .claude/skills/ -
Cursor .cursor/skills/ .agents/skills/, .claude/skills/
Gemini CLI .gemini/skills/ .agents/skills/
Codex CLI .agents/skills/ (primary) -
GitHub Copilot .github/skills/ .agents/skills/, .claude/skills/
Kiro .kiro/skills/ -
OpenCode .opencode/skills/ .agents/skills/, .claude/skills/
Pi .pi/skills/ .agents/skills/
Qoder .qoder/skills/ ~/.qoder/skills/ (user-level)
Trae China .trae-cn/skills/ TBD
Trae International .trae/skills/ TBD
Rovo Dev .rovodev/skills/ ~/.rovodev/skills/ (user-level)

All harnesses support the {skill-name}/SKILL.md directory structure with optional reference/, scripts/, and assets/ subdirectories.

Native Subagent Directory Structure

Harness Native directory File format
Claude Code .claude/agents/ (installed plugin) Markdown with YAML frontmatter
Codex CLI <skill>/agents/ (nested, auto-discovered) TOML

Impeccable keeps canonical agent prompts under skill/agents/ and emits provider-native files only for harnesses with documented subagent formats. Claude reads its agents from the installed plugin; Codex auto-discovers the TOML bundled inside the installed skill's own agents/ folder, so the normal skills install carries it with no separate sidecar.

Placeholder / Variable Substitution

Claude Code supports runtime variable substitution directly in SKILL.md bodies: $ARGUMENTS, $0-$N, ${CLAUDE_SKILL_DIR}, ${CLAUDE_SESSION_ID}. No other harness supports substitution in skills.

Some harnesses have separate "custom commands" systems (distinct from skills) with their own substitution:

Harness Command system Substitution syntax
Gemini CLI .gemini/commands/ (TOML) {{args}}, !{shell}, @{file}
Codex CLI .codex/prompts/ $ARGNAME
OpenCode .opencode/commands/ $ARGUMENTS, $1-$N, !`shell`

Our build system handles cross-provider placeholders at compile time via replacePlaceholders() for {{model}}, {{config_file}}, {{ask_instruction}}, and {{available_commands}}.

Reference in New Issue View Git Blame Copy Permalink