| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
New standalone create-v2mom skill (converted from the homelab
workflow template, markdown + YAML frontmatter, context-hygiene
references removed in favor of the global session-context protocol).
add-tests/SKILL.md gains a 'Core Principle — Refactor for Testability
First' section and three inserts into the phase instructions:
- Phase 1 flags testability-blocked functions during inventory
- Phase 2 surfaces refactor-first candidates per function
- Phase 3 adds a test-failure-vs-production-bug triage step
Sourced from the retired refactor.org homelab workflow (which was a
TDD-for-testability guide, not a general refactoring guide — general
refactoring is already covered by the /refactor slash command).
|
| | |
|
| |
|
|
| |
DoDAF / UAF / IDEF1X)
|
| |
|
|
| |
arc42)
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
problem-solving routing
Three improvements bundled together:
1. New hook — `destructive-bash-confirm.py` (PreToolUse/Bash):
Gates `git push --force`, `git reset --hard`, `git clean -f`,
`git branch -D`, and `rm -rf` behind a confirmation modal with the
command, local context (branch, uncommitted counts, targeted paths),
and a severity banner. Elevates severity when force-pushing protected
branches (main/master/develop/release/prod) or when rm -rf targets
root, home, or wildcard paths. Reuses _common.py.
2. Architecture suite rename — the "Part of the arch-* suite" footer in
arch-design, arch-decide, arch-document, arch-evaluate descriptions
now reads "Part of the architecture suite (arch-design / arch-decide
/ arch-document / arch-evaluate + c4-analyze / c4-diagram for
notation-specific diagramming)." Matching footers added to c4-analyze
and c4-diagram. c4-* keep their framework-specific prefix (C4 is a
notation, arch-* is framework-agnostic workflow) but are now
discoverable as suite members.
3. Problem-solving cluster routing — added YAML frontmatter with
descriptions (including "Do NOT use for X (use Y)" clauses) to
debug/SKILL.md and fix-issue/SKILL.md. Previously both had no
frontmatter at all, which broke skill-router discovery. The four
cluster members (debug, fix-issue, root-cause-trace, five-whys) now
route unambiguously by description alone.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Cross-cutting rule covering subagent hygiene:
- Decision table: parallel-safe (read-only investigation, independent
test failures, multi-domain research) vs sequential-with-review
(plan execution, coupled edits) vs never-parallel (concurrent writes)
vs don't-subagent-at-all (target known, work fits in ~10 tool calls).
- Prompt contract: scope / pasted context / explicit 'do NOT' list /
required output format. Missing any field yields shallow work.
- Context-pollution rule: subagents absorb noise the main thread
shouldn't carry. When one fails, dispatch a fix-agent with the
failure report — do not retry in the orchestrator.
- Review-gate cadence: after each sequential task, or every ~3 in
parallel batches.
- Anti-patterns including parallel implementation on overlapping
files, broad 'fix all the tests' prompts, timeout-tuning to mask
flakes, and letting the agent decide scope.
Added one-line cross-references to subagents.md from debug/,
review-code/, and finish-branch/ SKILL.md — the skills that most
rely on delegation.
Clean-room synthesis from NeoLabHQ/context-engineering-kit's
subagent-driven-development pattern (MIT).
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Consolidates stdin-parse and response-emit across the two confirm hooks
into `hooks/_common.py` (stdlib-only, sibling symlinked alongside the
hooks it serves). Net ~28 lines less duplication.
Adds a `systemMessage` banner alongside the confirmation modal when the
commit message or PR title/body contains AI-attribution patterns:
- Co-Authored-By: Claude|Anthropic|GPT|AI trailers
- 🤖 robot emoji
- "Generated with Claude Code" / similar footers
- "Created with …" / "Assisted by …" variants
Scanning targets structural leak patterns only — bare mentions of
"Claude" or "Anthropic" in diff context don't fire, so discussing the
tools themselves in a commit message doesn't false-positive.
Clean-room synthesis from GowayLee/cchooks (MIT) — specifically, the
systemMessage-alongside-reason pattern and event-aware stdin helpers.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Three new machine-wide hooks installed via `make install-hooks`:
- `precompact-priorities.sh` (PreCompact) — injects a priority block into
the compaction prompt so the generated summary retains information most
expensive to reconstruct: unanswered questions, root causes with
file:line, subagent findings as primary evidence, exact numbers/IDs,
A-vs-B decisions, open TODOs, classified-data handling.
- `git-commit-confirm.py` (PreToolUse/Bash) — gates `git commit` behind a
confirmation modal showing parsed message, staged files, diff stats,
author. Parses both HEREDOC and `-m`/`--message` forms.
- `gh-pr-create-confirm.py` (PreToolUse/Bash) — gates `gh pr create`
behind a modal showing title, base ← head, reviewers, labels,
assignees, milestone, draft flag, body (HEREDOC or quoted).
Makefile: adds `install-hooks` / `uninstall-hooks` targets and extends
`list` with a Hooks section. Install prints the settings.json snippet
(in `hooks/settings-snippet.json`) to merge into `~/.claude/settings.json`.
Also: `languages/elisp/claude/hooks/validate-el.sh` now emits JSON with
`hookSpecificOutput.additionalContext` on failure (via new `fail_json()`
helper) so Claude sees a structured error in context, in addition to
the existing stderr output and exit 2.
Patterns synthesized clean-room from fcakyon/claude-codex-settings
(Apache-2.0). Each hook is original content.
|
| |
|
|
| |
trigger
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
pattern)
Clean-room synthesis of the 'finishing a development branch' pattern from
obra/superpowers (MIT) — adopted as the forced-choice workflow scaffold,
not the substantive rules. Substantive rules defer to existing ones:
- Verification → verification.md
- Commit conventions + no AI attribution → commits.md
- Review discipline → review-code
Core patterns implemented:
- Phase 1 verify-before-options (hard-stop on failing tests)
- Phase 2 base branch + commit range + worktree detection
- Phase 3 forced-choice menu (exactly 4 options, no editorializing, stop+wait)
- Phase 4 execution per-option with:
- Option 1 (merge locally): re-verify after merge, delete branch, prompt
about remote-branch cleanup separately
- Option 2 (push + PR): gh pr create with inline template (no AI
attribution in the body); do NOT remove worktree
- Option 3 (keep): no git state changes; preserve worktree
- Option 4 (discard): typed-word "discard" confirmation gate required;
lists what will be permanently lost; force-delete + remote cleanup
- Phase 5 worktree cleanup matrix (cleanup for 1 and 4; preserve for 2 and 3)
Notable over the upstream superpowers skill:
- Explicit delegation to verification.md / commits.md / review-code rather
than re-teaching those standards inline
- Cross-references to /review-code (pre) and /arch-evaluate (if architectural)
- Handles remote-branch cleanup question separately from local branch
(upstream conflates them)
- "Common Mistakes" section names the specific failure modes this skill
prevents (open-ended "what now", accidental deletes, merge-then-oops,
worktree amnesia, trailing AI attribution in PRs)
Rubric coverage vs upstream: M (verify → options → execute → cleanup);
M (forced-choice menu pattern); M (typed-discard confirmation gate);
M (worktree cleanup matrix); M (hard-stop on failing tests);
+ (explicit deferral to existing rules vs upstream's inline rules);
+ (remote-branch cleanup as separate prompt); + (skill integration notes
for /review-code and /arch-evaluate); no dropped capabilities.
Makefile SKILLS extended; make install symlinks globally at
~/.claude/skills/finish-branch.
|
| | |
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
improvements
Renamed review-pr → review-code (the skill accepts PR, SHA range,
current branch, staged changes — "pr" was understating scope).
Rewrote SKILL.md with YAML frontmatter (previously header-style) and
merged useful patterns from two sources:
From obra/superpowers skills/requesting-code-review:
- Intent-vs-delivery grading (given plan/ADR/ticket)
- Mandatory Strengths section (three minimum)
- Per-issue Critical/Important/Minor severity (per-criterion
PASS/WARN/FAIL retained; complementary axes)
- Required verdict + 1-2 sentence reasoning
- Multi-input support (PR / SHA range / current branch / --staged)
- Sub-agent dispatch recommendation for heavy reviews
- Concrete filled-in example output
From the claude-plugins-official code-review plugin:
- Phase 0 eligibility gate (skip closed/draft/auto/trivial/already-reviewed)
- CLAUDE.md traversal + adherence criterion (reads root + per-directory
CLAUDE.md files; audits the diff against stated rules)
- Multi-perspective Phase 2: five passes (CLAUDE.md adherence, shallow
bug scan, git history context, prior PR comments, in-scope code
comments). For large reviews, dispatch as parallel sub-agents.
- Confidence filter (High/Medium/Low; drop Low before reporting)
- False-positive categories explicitly enumerated (pre-existing issues
on unmodified lines, lint/typecheck issues CI handles,
senior-wouldn't-call-out nitpicks, silenced issues with valid reason,
intentional scope changes, unmodified-line issues, framework-behavior
tests)
- Trust-CI discipline (don't run builds yourself)
Substance from the original review-pr kept verbatim:
- DeepSat-specific criteria (security, TDD evidence, conventions,
no-AI-attribution, API contracts, architecture layering, root-cause
discipline)
Size: 60 lines → 347 lines. Growth is structural (added phases, added
example, added perspectives, added filters) not verbose — each section
earns its lines.
NOT adopted from the plugin:
- GitHub comment output format (plugin posts PR comments; review-code
outputs a markdown report the user can paste if they want)
- "Generated with Claude Code" footer (violates no-AI-attribution rule)
- Specific 0/25/50/75/100 confidence scale (Critical/Important/Minor
covers the same signal with less ceremony)
Makefile SKILLS updated: review-pr → review-code. Old
~/.claude/skills/review-pr symlink removed; make install creates the
new one at ~/.claude/skills/review-code.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Previous wording — 'pairwise or continue with normal category coverage' —
muddled the choice. Category coverage (Normal/Boundary/Error) tests each
parameter individually and doesn't meaningfully address combinatorial
interaction questions.
Sharper framing: when a function has parameters that combine, the real
question is pairwise vs exhaustive (the M^N full factorial). Category
coverage is a separate axis — it handles the error-case and boundary-case
testing that parameter-value combinations don't.
New prompt cites specific counts:
'Function X has N parameters (M^N = Y exhaustive combinations).
Pairwise or exhaustive?'
Pairwise stays the pragmatic default; exhaustive only when the user names
a regulatory / safety-critical reason.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
existing testing skills
Forked verbatim from omkamal/pypict-claude-skill (MIT). LICENSE preserved.
Renamed from `pict-test-designer` to `pairwise-tests` — technique-first
naming so users invoking "pairwise" or "combinatorial" find it; PICT
remains the tool under the hood.
Bundle (skill-runtime only):
pairwise-tests/SKILL.md (renamed, description rewritten)
pairwise-tests/LICENSE (MIT, preserved)
pairwise-tests/references/pict_syntax.md
pairwise-tests/references/examples.md
pairwise-tests/scripts/pict_helper.py (Python CLI for model gen / output fmt)
pairwise-tests/scripts/README.md
Upstream's repo-level docs (README, QUICKSTART, CONTRIBUTING, etc.) and
`examples/` dir (ATM + gearbox walkthroughs — useful as reading, not as
skill-runtime) omitted from the fork. Attribution footer added.
Cross-references so /add-tests naturally routes to /pairwise-tests when
warranted:
- add-tests/SKILL.md Phase 2 step 8: if a function in scope has 3+ parameters
each taking multiple values, surface `/pairwise-tests` to the user before
proposing normal category coverage. Default continues with /add-tests;
user picks pairwise explicitly.
- claude-rules/testing.md: new "Combinatorial Coverage" section after the
Normal/Boundary/Error categories. Explains when pairwise wins, when to
skip (regulated / provably exhaustive contexts, ≤2 parameters, non-
parametric testing), and points at /pairwise-tests.
- languages/python/claude/rules/python-testing.md: new "Pairwise /
Combinatorial for Parameter-Heavy Functions" subsection under the
parametrize guidance. Explains the pytest workflow: /pairwise-tests
generates the matrix, paste into pytest parametrize block, or use
pypict helper directly.
Mechanism note: cross-references are judgment-based — Claude reads the
nudges in add-tests/testing/python-testing and acts on them when appropriate,
not automatic dispatch. Craig can still invoke /pairwise-tests directly when
he already knows he wants combinatorial coverage.
Makefile SKILLS extended; make install symlinks /pairwise-tests globally.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
extensions
Forked verbatim from anthropics/skills/skills/frontend-design (Apache 2.0).
LICENSE.txt preserved. Upstream SKILL.md prose (aesthetic guidance,
archetype list, anti-pattern callouts) kept intact.
Extensions added (clearly marked, load progressively — base SKILL.md
stays lean for simple cases):
SKILL.md:
- Description extended with explicit negative triggers: narrow
maintenance (single CSS bug, dependency upgrade, a11y-only retrofit),
operational contexts where stakeholder has specified "minimal,
functional, no creative direction," backend / API work, non-web UIs
(mobile native, desktop, terminal), and refactoring without visible
design component.
- New "Workflow" section at the end of SKILL.md: four phases (intake,
commitment, build, review) with pointers to reference files. Simple
component tweaks skip the workflow; non-trivial redesigns walk it.
- New "References" section: table mapping file → load-when condition.
- Attribution footer marking upstream source + what's locally added.
references/workflow.md (~150 lines)
Intake questions (purpose, audience, operational context, functional
priority, technical constraints, brand references, success criteria).
Commitment step (archetype pick, trade-offs, font pairing, palette,
motion, layout as one-line decisions). Build reminders. Review
pointer. Guidance on when to skip phases.
references/accessibility.md (~200 lines)
WCAG AA contrast thresholds + practical check guidance. Keyboard
navigation + focus management. Semantic HTML + ARIA rules. Reduced-
motion CSS snippet. Smoke checklist. Operational-context note for
defense / ISR work.
references/responsive.md (~160 lines)
Mobile-first vs desktop-first decision. Named breakpoints (Tailwind-
style) vs magic pixels. Container queries. Aesthetic translation
table — how each archetype handles small-screen scaling. Responsive
typography with clamp(). Operational-dashboard note: desktop-primary
is a legitimate product decision.
references/design-review.md (~170 lines)
Archetype check (does the build read as what was committed to?).
Anti-pattern grep for fonts, palette, layout, motion, backgrounds,
components. Code-quality-match check (ornate design + lazy code =
failure). Performance sanity. Convergence check (if last 3 builds
all used the same archetype, break the pattern). The one-sentence
test for memorability.
references/rationale-template.md (~160 lines)
Template for design-rationale.md alongside the build. Nine sections
(purpose, archetype, locked decisions, deliberately absent,
accessibility, responsive, implementation, open questions,
references). Filled example using a DeepSat SOCOM demo landing page
to show density and specificity.
Structure matches Anthropic's own pdf / docx / webapp-testing pattern
(SKILL.md entry + references/ for progressive disclosure). Makefile
SKILLS extended; make install symlinks globally.
Adoption caveat resolved: name kept as `frontend-design` (not renamed
to ui-design) — "frontend" signals scope (web code, not mobile /
desktop / terminal UIs), upstream parity preserved for attribution.
|
| |
|
|
|
|
|
|
|
|
|
|
| |
Per-hunk prompt inside the skill is editor-independent — works on machines
without Emacs available. The git-style-markers approach required smerge-mode
or ediff to be pleasant, and Craig can't assume Emacs on every machine.
Side-by-side file fallback still applies when the baseline is missing or
corrupt (can't run a 3-way merge in the first place).
Emacs users can optionally drop into ediff via smerge-ediff — listed as a
v2+ enhancement.
|
| | |
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Two fixes rolled up:
1. Add .gitignore with **/node_modules/, package-lock.json, Python venv /
cache artifacts, and OS metadata. Prior make deps run produced a 603-
file playwright-js/node_modules tree that should never be tracked.
2. Makefile deps target: install playwright-py via `uv tool install
playwright` instead of `pip install --system`. Earlier attempts with
pip --user, pip --system, and uv pip --system all failed on externally-
managed Python (PEP 668 on Arch). `uv tool install` creates an isolated
venv for the CLI, avoiding the conflict. Chromium browsers are shared
with the JS side via ~/.cache/ms-playwright — no re-download.
Also added uv itself to the deps target (was missing).
Library import (`import playwright`) still requires per-project venv,
which is the right pattern on externally-managed systems. Deps output
mentions this explicitly.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Rename `playwright-skill/` → `playwright-js/` and add `playwright-py/`
as a verbatim fork of Anthropic's official `webapp-testing` skill
(Apache-2.0). Cross-pollinate: each skill gains patterns and helpers
inspired by the other's strengths, with upstream semantics preserved.
## playwright-js (JS/TS stack)
Renamed from playwright-skill; upstream lackeyjb MIT content untouched.
New sections added (clearly marked, preserving upstream semantics):
- Static HTML vs Dynamic Webapp decision tree (core Anthropic methodology)
- Reconnaissance-Then-Action pattern (navigate → networkidle → inspect → act)
- Console Log Capture snippet (page.on console/pageerror/requestfailed)
Description updated to clarify JS/TS stack fit (React/Next/Vue/Svelte/Node)
and reference `/playwright-py` as the Python sibling.
## playwright-py (Python stack)
Verbatim fork of anthropics/skills/skills/webapp-testing; upstream SKILL.md
and bundled `scripts/with_server.py` + examples kept intact. New scripts
and examples added (all lackeyjb-style conveniences in Python):
Scripts:
scripts/detect_dev_servers.py Probe common localhost ports for HTTP
servers; outputs JSON of found services.
scripts/safe_actions.py safe_click, safe_type (retry-wrapped),
handle_cookie_banner (common selectors),
build_context_with_headers (env-var-
driven: PW_HEADER_NAME / PW_HEADER_VALUE /
PW_EXTRA_HEADERS='{…json…}').
Examples:
examples/login_flow.py Login form + wait_for_url.
examples/broken_links.py Scan visible external hrefs via HEAD.
examples/responsive_sweep.py Multi-viewport screenshots to /tmp.
SKILL.md gains 5 "Added:" sections documenting the new scripts, retry
helpers, env-header injection, and /tmp script discipline. Attribution
notes explicitly mark upstream vs local additions.
## Makefile
SKILLS: playwright-skill → playwright-js + playwright-py
deps target: extended Playwright step to install Python package +
Chromium via `python3 -m pip install --user playwright && python3 -m
playwright install chromium` when playwright-py/ is present. Idempotent
(detected via `python3 -c "import playwright"`).
## Usage
Both skills symlinked globally via `make install`. Invoke whichever
matches the project stack — cross-references in descriptions route you
to the right one. Run `make deps` once to install both runtimes.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Browser automation + UI testing skill forked verbatim from
github.com/lackeyjb/playwright-skill (MIT, 2458 stars, active through
Dec 2025). LICENSE preserved in skill dir with attribution footer added
to SKILL.md.
Bundle contents (from upstream):
playwright-skill/SKILL.md
playwright-skill/API_REFERENCE.md
playwright-skill/run.js (universal executor with module resolution)
playwright-skill/package.json
playwright-skill/lib/helpers.js (detectDevServers, safeClick, safeType,
takeScreenshot, handleCookieBanner,
extractTableData, createContext with
env-driven header injection)
playwright-skill/LICENSE (MIT, lackeyjb)
Makefile updates:
- SKILLS extended with playwright-skill; make install symlinks it
globally into ~/.claude/skills/
- deps target extended to check node + npm, and to run the skill's
own `npm run setup` (installs Playwright + Chromium ~300 MB on
first run). Idempotent: skipped if node_modules/playwright
already exists.
Stack fit: JavaScript Playwright aligns with Craig's TypeScript/React
frontend work. Python-side (Django) browser tests would be better served
by Anthropic's official webapp-testing skill (Python Playwright bindings),
noted in the evaluation memory but not adopted here — minimal overlap,
easy to add later if the need arises.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Distilled from NeoLab customaize-agent:prompt-engineering rubric (GPL-3.0
source; clean-room, no prose reused). ~17 KB NeoLab version trimmed to
tighter ~430 lines focused on what's genuinely non-obvious:
- Four prompt-type classification (discipline-enforcing / guidance /
collaborative / reference), with explanations for each so the user
knows what they're picking. Used in both design and critique modes.
- Seven persuasion principles (Meincke et al. 2025, N≈28,000), with
by-type matrix. Notably flags Liking as actively harmful for
collaborative prompts (breeds sycophancy in reviews/critiques).
- Degrees-of-freedom axis (high/medium/low) matched to task fragility.
- Context-window-as-shared-resource framing.
- Brief reference only for classical techniques (few-shot, CoT, system
prompts, templates) — widely documented elsewhere, not re-taught.
- Explicit ethics test for persuasion use.
- Design-mode vs critique-mode workflows.
- Anti-patterns list covering sycophancy-by-default, hedging-on-
discipline-prompts, authority-stack-on-guidance, high-freedom-on-
fragile-tasks.
Landscape: no prompt-engineering skill exists in Anthropic's official
repo, wshobson/agents, or the major community skill collections. Real gap.
Makefile SKILLS extended; global symlink installed.
|
| |
|
|
|
|
|
|
|
|
|
|
|
| |
"memorize" implied passive storage (same mental model as auto-memory).
"codify" captures the actual operation: editorial selection, specific
phrasing, deliberate commit to a lasting artifact.
Changes:
- memorize/ → codify/
- SKILL.md: name: codify; title updated; all references changed
- Default CLAUDE.md section: ## Memorized Insights → ## Codified Insights
- Makefile SKILLS updated
- Old ~/.claude/skills/memorize symlink removed; codify symlink created
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Four new skills synthesized from patterns in NeoLabHQ/context-engineering-kit
(GPL-3.0). Clean-room approach: extracted rubrics from the originals
(triggers, phases, hard cases, footguns, novel patterns), then wrote from
scratch without referencing their prose. Ideas and methods aren't copyrightable;
wording is. These skills are independent works.
brainstorm Turn a vague idea into a validated design doc. Three
phases: one-question-at-a-time dialogue, six-approach
exploration (three conventional + three diverse tail
samples for anti-convergence), chunked design
presentation with per-chunk validation. Output:
docs/design/<topic>.md. Hands off to arch-decide /
arch-design / implementation.
memorize Curate session insights into project CLAUDE.md under a
dedicated "## Memorized Insights" section. Grow-and-
refine per ACE (arXiv:2510.04618): atomic, evidence-
backed, non-redundant bullets. Args: --dry-run, --max,
--target, --section, --source. Flags cross-project
patterns for promotion to ~/code/rulesets/claude-rules/.
Clearly delineates from auto-memory (private) and
formal rules (stable policy).
root-cause-trace Backward-walk technique for debugging. Observe symptom
→ identify immediate cause → walk up the call chain →
find original trigger → fix at source + defense-in-
depth at each intermediate layer. Instrumentation
guidance (stack capture before the dangerous op, not
after; stderr not framework logger in tests); test-
pollution bisection. Companion to /debug — /debug is
broader; this is specifically the backward walk.
five-whys Iterative why-questioning from symptom to process/
decision root cause. Five is a convention, not a
quota — stop when a cause, if eliminated, would prevent
every symptom in the chain. Handles branching (multiple
contributing causes). Validates chains by walking back
from root to symptom. Refuses to terminate at "human
error" or "not enough budget" — those have deeper
whys. Companion to root-cause-trace (that's for code
execution; this is for process).
Makefile SKILLS extended. make install symlinks all four into
~/.claude/skills/ alongside existing skills. Lint clean.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Four chained Claude Code skills covering the full architecture lifecycle:
arch-design Intake (stakeholders, scale, quality attributes, constraints)
→ candidate paradigms with honest trade-off analysis
→ recommendation + open-decision list
→ .architecture/brief.md
arch-decide ADR creation and management. Five template variants (MADR,
Nygard, Y-statement, lightweight, RFC). Lifecycle, review
process, adr-tools automation.
Forked from wshobson/agents (MIT). LICENSE preserved.
arch-document Full arc42-structured documentation (12 sections) from brief
+ ADRs + codebase. Dispatches to c4-analyze / c4-diagram for
Context, Building Block, Runtime, Deployment diagrams.
arch-evaluate Audits implementation against stated architecture.
Framework-agnostic checks (cyclic deps, stated-layer
violations, public API drift, forbidden deps) run on any
language. Opportunistically invokes language-specific linters
when configured (dependency-cruiser for TS, import-linter for
Python, go vet + depguard for Go). Never installs tooling.
Supporting docs at docs/architecture/:
- README.md suite overview, install steps, per-language linter install
commands (Python import-linter, TS dependency-cruiser, Go
golangci-lint, Java ArchUnit future, C/C++ IWYU future),
typical flow through the chain
- v2-todo.org deferred features (auto-gen linter configs, ArchUnit, CI
mode, DDD aggregate boundaries, visual dep graphs, retroactive
layering inference)
Makefile SKILLS extended with the four new entries; make install symlinks
them to ~/.claude/skills/ alongside existing skills.
Landscape: arch-decide fills the well-covered ADR bucket by adopting the
strongest community offering rather than reinventing. arch-design and
arch-evaluate fill gaps where no general-purpose skill existed. arch-document
fills the arc42 gap (C4 diagrams already covered by sibling skills).
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Additions to claude-rules/testing.md:
- Testing pyramid proportions (70-80% unit / 15-25% integration / 5-10% e2e)
- Integration Tests section: docstring must name 'Components integrated:'
and mark real vs mocked; when-to-write heuristics
- Signs of Overmocking: 'would the test pass if the function body was
NotImplementedError?' plus three more sharp questions
- Testing Code That Uses Frameworks: test your integration, not the
framework itself
- Test Real Code, Not Copies: never inline prod code into tests
- Error Behavior, Not Error Text: test type + key values, not exact prose
- If Tests Are Hard to Write, Refactor the Code: hard-to-test is a code
signal, not a test signal; extract focused helpers
- Anti-patterns list extended
Addition to languages/elisp/claude/rules/elisp-testing.md:
- Interactive vs Internal split pattern: cj/foo wraps cj/--foo; test the
internal directly, skip UI mocks
Source: ~/.emacs.d/ai-prompts/quality-engineer.org (personal reference,
kept as an extended prompt separate from these rules).
|
| |
|
|
|
|
|
|
| |
- elisp-testing.md: generalized testutil description. The specific files
testutil-general.el / testutil-filesystem.el / testutil-org.el only
exist in one project; bundle should describe the pattern, not name
specific files.
- README.org: install examples use ~/code/ path to match actual layout.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
| |
New generic rule at claude-rules/commits.md covers author identity,
absence of Claude/Anthropic/LLM/AI attribution (messages, PRs,
comments, trailers, emojis), and conventional commit format. Applies
to all repos.
Bundle settings.json now sets attribution.commit: "" and
attribution.pr: "" so Claude Code's default attribution is suppressed
belt-and-suspenders with the written rule.
Elisp CLAUDE.md template trimmed to reference commits.md instead of
inlining the rules.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Ports useful quality-of-life targets from DeepSat's coding-rulesets
Makefile, adapted to this repo's two-scope (global + per-project)
structure.
New targets:
make deps Install claude, jq, fzf, ripgrep,
emacs via brew/apt/pacman. Idempotent
(skips already-present tools). For
new machines and VMs.
make diff LANG=<lang> [PROJECT=<path>]
Show unified diff between repo source
and installed copies in a target
project. CLAUDE.md excluded (seed-
only, diverges by design).
make lint Validate ruleset structure: top-level
headings, 'Applies to:' headers on
rule files, shebangs and exec bits on
hook scripts.
Infrastructure:
- Help migrated to awk-parsed ##@/## pattern; new targets document
themselves via a single trailing `## ...` comment.
- fzf-picker fallback: if PROJECT= is unset, install-lang and diff
launch fzf over local .git dirs under $HOME. Keeps PROJECT=<path>
for scripts/automation; only interactive users hit fzf.
scripts/diff-lang.sh Walks the file list the installer would copy,
diffs each against the target.
scripts/lint.sh Standalone ruleset structure validator.
|
| | |
|
| |
|
|
|
|
| |
The validate-el.sh hook byte-compiles .el files, which produces .elc
(and on Emacs 28+ with native-comp, .eln) artifacts. Projects using
the bundle almost always want these ignored.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Byte-compile needs external packages on the load path to resolve
(require ...) forms in project files. Without this, any project using
MELPA/ELPA packages (dash, s, etc.) failed Phase 1 with "Cannot open
load file".
package-initialize reads package-user-dir (default ~/.emacs.d/elpa)
and exposes installed package autoloads. Small latency cost (~100ms)
but makes the hook work on real projects.
Verified:
- chime.el (requires dash) now byte-compiles cleanly; was failing.
- emacs.d modules still pass; no regression.
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Phase 2 test lookup now triggers for any .el file outside tests/, not
just modules/*.el. Stem-based test matching works the same way; this
just broadens the case pattern.
Before: only modules/foo.el → tests/test-foo*.el triggered Phase 2.
After: foo.el, lib/foo.el, modules/foo.el all do.
init.el and early-init.el are still Phase-1-only (byte-compile would
load the full package graph).
Verified on:
- emacs.d (modules/-based): modules/browser-config.el still runs
its matching test, exit 0
- flat layout (scratch /tmp): source.el at project root successfully
finds and runs tests/test-source.el
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
claude-rules/testing.md is now language-agnostic (TDD principles, test
categories, coverage targets, anti-patterns). Scope header widened to
**/*. Python-specific content (pytest, fixtures, parametrize, anyio,
Django DB testing) moved to languages/python/claude/rules/python-testing.md.
Added languages/python/ bundle (rules only so far; no CLAUDE.md template
or hooks yet — Python validation tooling differs from Elisp). Added
install-python shortcut to the Makefile.
Updated scripts/install-lang.sh to copy claude-rules/*.md into each
target project's .claude/rules/. Bundles no longer need to carry their
own verification.md copy — deleted languages/elisp/claude/rules/verification.md.
Single source of truth in claude-rules/, fans out via install.
Elisp-testing.md now references testing.md as its base (matches the
python-testing.md pattern).
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Introduces a second install mode alongside the existing global symlinks:
per-project language bundles that copy a language-specific Claude Code
setup (rules, hooks, settings, pre-commit) into a target project.
Layout additions:
languages/elisp/ - Emacs Lisp bundle (rules, hooks, settings, CLAUDE.md)
scripts/install-lang.sh - shared install logic
Makefile additions:
make help - unified help text
make install-lang LANG=<lang> PROJECT=<path> [FORCE=1]
make install-elisp PROJECT=<path> [FORCE=1] (shortcut)
make list-languages - show available bundles
Elisp bundle contents:
- CLAUDE.md template (seed on first install, preserved on update)
- .claude/rules/elisp.md, elisp-testing.md, verification.md
- .claude/hooks/validate-el.sh (check-parens, byte-compile, run matching tests)
- .claude/settings.json (permission allowlist, hook wiring)
- githooks/pre-commit (secret scan + staged-file paren check)
- gitignore-add.txt (append .claude/settings.local.json)
Hooks use \$CLAUDE_PROJECT_DIR with a script-relative fallback, so the
same bundle works on any machine or clone path. Install activates git
hooks via core.hooksPath=githooks automatically. Re-running install is
idempotent; CLAUDE.md is never overwritten without FORCE=1.
|
| |
|
|
|
|
|
|
|
|
|
|
| |
The hooks/settings.json template was broken since day one:
- PostEditTool is not a valid Claude hook event
- PreCommit is not a Claude concept at all
- matcher was used as a glob, not a tool-name regex
- $FILE was never substituted from stdin JSON
Hooks never fired. Formatting and secret-scanning belong in CI and
pre-commit frameworks, not per-developer Claude config. Remove the
template and its install-hooks Makefile target.
|
| |
|
|
|
|
|
|
|
|
|
| |
Hooks provide:
- PostEditTool: ruff format/check on Python, terraform fmt on .tf
- PreCommit: block commits containing hardcoded secrets (AWS keys, API tokens, passwords)
Install per-project with: make install-hooks TARGET=/path/to/project
Won't overwrite existing settings.json — shows diff command instead.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
Skills (adapted from DeepSat, stripped of project-specific references):
- /review-pr: PR review against engineering standards
- /fix-issue: issue-to-merge TDD workflow
- /security-check: secrets, OWASP, and dependency audit
- /debug: systematic 4-phase debugging
- /add-tests: test coverage analysis and generation
- /respond-to-review: evaluate and implement code review feedback
Rules (general-purpose, copied as-is):
- testing.md: universal TDD standards and anti-patterns
- verification.md: proof over assumption
Makefile updated to install both skills and rules via symlinks.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
|
|
Two skills for generating C4 model diagrams as draw.io XML:
- /c4-analyze: generates diagrams from codebase analysis
- /c4-diagram: generates diagrams from conversational description
Includes Makefile for symlink-based install to ~/.claude/skills/.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
