Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
{
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
"name": "greybeard",
"description": "Greybeard — Karpathy-inspired coding-agent guidelines, the skillify / check-resolvable meta-skills, and the /scalable decision test.",
"description": "Greybeard — Karpathy-inspired coding-agent guidelines, the skillify / check-resolvable meta-skills, and the /pressure-test decision test.",
"owner": {
"name": "Clawnify",
"url": "https://github.com/clawnify"
},
"plugins": [
{
"name": "greybeard",
"description": "skillify + check-resolvable skills and the /scalable command. Pair with the npx installer for the always-on guidelines.",
"description": "skillify + check-resolvable skills and the /pressure-test command. Pair with the npx installer for the always-on guidelines.",
"source": "./",
"category": "productivity"
}
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "greybeard",
"description": "Karpathy-inspired coding-agent skills: skillify (capture repeated work), check-resolvable (keep skills DRY + MECE), and the /scalable decision test.",
"description": "Karpathy-inspired coding-agent skills: skillify (capture repeated work), check-resolvable (keep skills DRY + MECE), and the /pressure-test decision test.",
"author": {
"name": "Clawnify",
"url": "https://github.com/clawnify"
Expand Down
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@

> Built and maintained by [Clawnify](https://clawnify.com) — a managed platform that provisions AI agents with WhatsApp / Telegram / Email and browser capabilities for non-technical users.

A single `CLAUDE.md` file to improve AI coding-agent behavior, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls, plus three sections we added for the AI-assisted-coding era. Ships with two runnable [meta-skills](#skills-skillify-dry--mece-resolvers), the [`/scalable`](#the-scalable-command) decision command, the [`/sidenote`](#the-sidenote-command) park-a-thought command, and a [one-command installer](#install) that fans it all out to every AI coding agent you use.
A single `CLAUDE.md` file to improve AI coding-agent behavior, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls, plus three sections we added for the AI-assisted-coding era. Ships with two runnable [meta-skills](#skills-skillify-dry--mece-resolvers), its two main commands — [`/pressure-test`](#the-pressure-test-command), the decision test, and [`/sidenote`](#the-sidenote-command), park-a-thought and a [one-command installer](#install) that fans it all out to every AI coding agent you use.

## The Problems

Expand Down Expand Up @@ -182,17 +182,21 @@ The principle above ships as two runnable meta-skills in [`skills/`](./skills)

They're standard [Claude Code Agent Skills](https://code.claude.com/docs/en/skills) (portable to Cursor, Codex, OpenClaw). Install and usage: [`skills/README.md`](./skills/README.md).

## The `/scalable` command
## The two main commands

[`commands/scalable.md`](./commands/scalable.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out.
Greybeard's two flagship slash commands are **`/pressure-test`** and **`/sidenote`** — one guards the *quality* of a decision, the other guards your *focus* while you make it. The skills and always-on guidelines back them up, but these are the two you'll reach for by hand.

## The `/pressure-test` command

[`commands/pressure-test.md`](./commands/pressure-test.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out.

```bash
mkdir -p ~/.claude/commands
cp commands/scalable.md ~/.claude/commands/ # personal, all projects
cp commands/pressure-test.md ~/.claude/commands/ # personal, all projects
# or: .claude/commands/ for one project
```

Then `/scalable` (tests the current direction) or `/scalable <a specific decision>`.
Then `/pressure-test` (tests the current direction) or `/pressure-test <a specific decision>`.

## The `/sidenote` command

Expand All @@ -218,7 +222,7 @@ Then `/sidenote <the thought>` to park one, or `/sidenote` to see what's parked.
npx @clawnify/greybeard
```

It detects the AI coding agents you actually use and installs the right files for each: the seven guidelines into the rule file each one reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`, `.github/copilot-instructions.md`), plus the `skillify` / `check-resolvable` skills and the `/scalable` command for Claude Code and OpenClaw. Shared files are edited between markers, so re-running is a safe no-op and your own content is preserved.
It detects the AI coding agents you actually use and installs the right files for each: the seven guidelines into the rule file each one reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`, `.github/copilot-instructions.md`), plus the `skillify` / `check-resolvable` skills and the `/pressure-test` command for Claude Code and OpenClaw. Shared files are edited between markers, so re-running is a safe no-op and your own content is preserved.

```bash
npx @clawnify/greybeard --list # show detected agents
Expand All @@ -230,14 +234,14 @@ npx @clawnify/greybeard --uninstall # remove what it added

Supported: **Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, Codex, Gemini CLI, OpenClaw** — and any agent that reads `CLAUDE.md` / `AGENTS.md`.

**Claude Code plugin marketplace** (the skills + `/scalable` + always-on guidelines):
**Claude Code plugin marketplace** (the skills + `/pressure-test` + always-on guidelines):

```
/plugin marketplace add clawnify/greybeard
/plugin install greybeard
```

The plugin ships a `SessionStart` / `SubagentStart` hook that injects the three-pillars decision test (scalable / long term / efficient — the core of `/scalable`) into every session automatically — installing the plugin is enough, no per-project `npx` run needed. It's careful not to double up: if the full guidelines are already in your `~/.claude/CLAUDE.md` or a project's `CLAUDE.md` / `AGENTS.md` (via the npx installer or a hand-merge), the hook detects them and stays silent. To turn injection off without uninstalling, set `GREYBEARD=off` in your environment.
The plugin ships a `SessionStart` / `SubagentStart` hook that injects the three-pillars decision test (scalable / long term / efficient — the core of `/pressure-test`) into every session automatically — installing the plugin is enough, no per-project `npx` run needed. It's careful not to double up: if the full guidelines are already in your `~/.claude/CLAUDE.md` or a project's `CLAUDE.md` / `AGENTS.md` (via the npx installer or a hand-merge), the hook detects them and stays silent. To turn injection off without uninstalling, set `GREYBEARD=off` in your environment.

**Manual** (just the guidelines, one file — no Node):

Expand Down
8 changes: 5 additions & 3 deletions bin/install.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
// greybeard — cross-platform installer.
//
// Detects the AI coding agents on your machine / in this project and installs
// the Karpathy-inspired guidelines (+ Claude Code skills and the /scalable
// the Karpathy-inspired guidelines (+ Claude Code skills and the /pressure-test
// command) into each one's rule location. Pure Node stdlib, zero runtime deps.
//
// npx @clawnify/greybeard # install for every detected agent
Expand Down Expand Up @@ -144,14 +144,16 @@ function installClaude(dir, un) {
removeFenceFrom(path.join(dir, 'CLAUDE.md'));
removePath(path.join(dir, 'skills', 'skillify'));
removePath(path.join(dir, 'skills', 'check-resolvable'));
removePath(path.join(dir, 'commands', 'scalable.md'));
removePath(path.join(dir, 'commands', 'scalable.md')); // legacy name, pre-rename
removePath(path.join(dir, 'commands', 'pressure-test.md'));
removePath(path.join(dir, 'commands', 'sidenote.md'));
return;
}
fenceInto(path.join(dir, 'CLAUDE.md'), PRINCIPLES);
copyDir(path.join(PKG, 'skills', 'skillify'), path.join(dir, 'skills', 'skillify'));
copyDir(path.join(PKG, 'skills', 'check-resolvable'), path.join(dir, 'skills', 'check-resolvable'));
writeFile(path.join(dir, 'commands', 'scalable.md'), fs.readFileSync(path.join(PKG, 'commands', 'scalable.md'), 'utf8'));
removePath(path.join(dir, 'commands', 'scalable.md')); // clean up the pre-rename command from prior installs
writeFile(path.join(dir, 'commands', 'pressure-test.md'), fs.readFileSync(path.join(PKG, 'commands', 'pressure-test.md'), 'utf8'));
writeFile(path.join(dir, 'commands', 'sidenote.md'), fs.readFileSync(path.join(PKG, 'commands', 'sidenote.md'), 'utf8'));
}

Expand Down
File renamed without changes.
6 changes: 3 additions & 3 deletions hooks/greybeard-activate.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
// greybeard — SessionStart / SubagentStart hook.
//
// Injects the three-pillars decision test (scalable / long term / efficient —
// the core of the /scalable command) as hidden context so installing the
// the core of the /pressure-test command) as hidden context so installing the
// plugin is enough — no per-project `npx @clawnify/greybeard` needed.
// Skips injection when the full guidelines are already loaded another way:
//
Expand Down Expand Up @@ -48,7 +48,7 @@ function alreadyLoaded(cwd) {
return false;
}

// The three pillars, condensed from commands/scalable.md — the single
// The three pillars, condensed from commands/pressure-test.md — the single
// question that governs every decision. Keep wording in sync with that file.
const PILLARS = `GREYBEARD ACTIVE — judge every decision against the three pillars: whatever is **scalable**, **long term**, and **cannot be done in a more efficient way**.

Expand All @@ -62,7 +62,7 @@ If the pillars aren't concrete for the decision at hand, define them first: name

"No time to do it properly" is usually a stale pre-AI estimate; the proper version often fits this session. If it genuinely doesn't, say so and let the user decide — don't silently downgrade to the shortcut. When a shortcut is right, mark it inline with its ceiling and upgrade trigger.

For contested decisions, run the /scalable command (greybeard:scalable) to pressure-test the approach.`;
For contested decisions, run the /pressure-test command (greybeard:pressure-test) to pressure-test the approach.`;

function main() {
if ((process.env.GREYBEARD || '').trim().toLowerCase() === 'off') return;
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@clawnify/greybeard",
"version": "0.1.0",
"description": "Greybeard — Karpathy-inspired guardrails that make your AI coding agent behave like a principled senior engineer. Guidelines + skillify / check-resolvable skills + the /scalable decision test, installable across every AI coding agent.",
"description": "Greybeard — Karpathy-inspired guardrails that make your AI coding agent behave like a principled senior engineer. Guidelines + skillify / check-resolvable skills + the /pressure-test decision test, installable across every AI coding agent.",
"license": "MIT",
"homepage": "https://github.com/clawnify/greybeard",
"repository": {
Expand Down
Loading