@chanom/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @chanom/cli
 
-Interactive CLI that brews dev tooling config into your project - oxlint, oxfmt, knip, VS Code settings, and commit hooks, picked with a couple of prompts.
+Interactive CLI that brews dev tooling config into your project - oxlint, oxfmt, knip, VS Code settings, agent coding standards, and commit hooks, picked with a couple of prompts.
 
 ## Install
 
@@ -39,6 +39,7 @@ Debug mode logs each step (detected package manager, planned packages, every com
    - `oxfmt` - fast Rust-based formatter
    - `knip` - dead code remover
    - `vscode` - editor settings + extension recommendations
+   - `skills` - coding standards for AI agents (`.claude/skills`)
 2. **Sweetness** - how strict to be:
    - `light` - warn only, no blocking
    - `medium` - block on commit via husky + lint-staged + commitlint
@@ -61,12 +62,13 @@ installing anything. `light` sweetness works anywhere in the repo.
 
 ## What gets added
 
-| Topping  | Config file                                        | Scripts added            |
-| -------- | -------------------------------------------------- | ------------------------ |
-| `oxlint` | `oxlint.config.ts`\*                               | `lint`, `lint:fix`       |
-| `oxfmt`  | `oxfmt.config.ts`\*                                | `format`, `format:check` |
-| `knip`   | `knip.config.ts`\*                                 | `knip`                   |
-| `vscode` | `.vscode/settings.json`, `.vscode/extensions.json` | none                     |
+| Topping  | Config file                                                                     | Scripts added            |
+| -------- | ------------------------------------------------------------------------------- | ------------------------ |
+| `oxlint` | `oxlint.config.ts`\*                                                            | `lint`, `lint:fix`       |
+| `oxfmt`  | `oxfmt.config.ts`\*                                                             | `format`, `format:check` |
+| `knip`   | `knip.config.ts`\*                                                              | `knip`                   |
+| `vscode` | `.vscode/settings.json`, `.vscode/extensions.json`                              | none                     |
+| `skills` | `.agents/skills/coding-standards/`, `.claude/skills/coding-standards` (symlink) | none                     |
 
 \* `.mts` instead of `.ts` when your project is CommonJS (no `"type": "module"` in `package.json`).
 
@@ -80,6 +82,13 @@ on save (`editor.formatOnSave` stays off so both run in one pass), points
 teammates are prompted to install it. Only portable settings are written - no
 `cSpell.words` or other repo-specific entries.
 
+The `skills` topping also installs no packages and adds no scripts. It writes
+the `coding-standards` agent skill - a router `SKILL.md` plus TypeScript, React,
+and Vitest references - into `.agents/skills/coding-standards/`, so any agent
+tool can read it, and links `.claude/skills/coding-standards` at that directory
+with a relative symlink rather than keeping a second copy. The standards target
+the stack chanom scaffolds (Vite + React + TypeScript, oxlint, oxfmt, vitest).
+
 `medium` sweetness additionally adds:
 
 - `husky` - installed via `husky init`
@@ -105,6 +114,10 @@ Existing setup is never overwritten:
   setting you already have wins (and is warned about), and existing extension
   recommendations are kept. A `.vscode` file that can't be parsed as JSON (e.g. it
   has comments) is left untouched with a warning.
+- Skill files already on disk are warned about and skipped, and an existing
+  `.claude/skills/coding-standards` (a link of your own, or a real directory you
+  maintain by hand) is left alone - so re-running never overwrites standards you
+  have edited.
 
 The final commit uses your git identity; if none is configured, a local `Chanom <chanom@local>` identity is set. If committing fails (e.g. a commit hook rejects it), your files stay staged and `brew` tells you to commit manually.
 

package/dist/index.js

@@ -239,6 +239,50 @@ var Prompter = class extends Effect.Service()("internal/Prompter", { succeed: {
 		return { stop: (stopMessage) => Effect.sync(() => s.stop(stopMessage)) };
 	})
 } }) {};
+/** Every skill chanom can install, in install order. */
+const SKILLS = [{
+	name: "coding-standards",
+	files: [
+		{
+			"path": "references/react.md",
+			"contents": "# React\n\nReact 19 with the Vite plugin. Entry is `src/main.tsx`, which mounts `App` from\n`src/app.tsx` in `StrictMode`.\n\n## Structure\n\n`src/` grows by role as the app does: `components/`, `hooks/`, `utils/`,\n`pages/`, `providers/`. Feature-scoped code lives under `features/<name>/` and\nmirrors that same layout. Put code in the feature folder unless two features\nshare it.\n\n## Components\n\n- **Container / presentational**: containers fetch data and hold logic;\n  presentational components take props and return JSX with no side effects.\n- Props are wrapped in `Readonly<>`:\n  `export function UserCard({ name }: Readonly<UserCardProps>)`.\n- Conditional rendering uses a ternary (`isOpen ? <Panel /> : null`), never\n  `&&` — a falsy number renders as `0`.\n- Every component exports inline. `default` export is reserved for route-level\n  page components.\n- Shared state lives in a context provider under `providers/`. Reach for\n  context only once prop-passing spans three levels.\n\n## Hooks\n\nCustom hooks are named `use-<thing>.ts` and return an object, not a positional\ntuple, once they return more than two values. Every effect declares its full\ndependency array; an effect with no cleanup and no async work is usually a\nrender-time computation instead.\n"
+		},
+		{
+			"path": "references/typescript.md",
+			"contents": "# TypeScript\n\n## Types\n\n- Never use `any`. Reach for generics and utility types; when you must escape\n  the type system use `unknown` and narrow explicitly.\n- Type-only imports use `import type { ... }`. A mixed import splits its type\n  part into a separate `import type` line.\n- Derive types from their source rather than restating them — `z.infer` for a\n  schema, `ReturnType`/`Parameters` for a function, `typeof` for a const object.\n  A hand-written duplicate drifts.\n- Props and params objects are declared as `interface`, named after their owner:\n  `interface UserCardProps`, `interface UseCurrentUserParams`.\n\n## Modules\n\n- Functions, not classes. Hooks, utils, factories, and components are plain\n  exported functions.\n- Export inline (`export function formatDate(...)`) rather than a trailing\n  `export { ... }` block.\n- Import order is enforced by oxlint — run `pnpm lint --fix` rather than\n  hand-sorting.\n\n## Errors\n\nThrow `Error` (or a subclass) with a message naming what failed and the value\nthat caused it. An unused catch binding is omitted: `catch {`, not\n`catch (_e) {`.\n"
+		},
+		{
+			"path": "references/vitest.md",
+			"contents": "# Vitest\n\nTests run on jsdom with globals enabled — `describe`, `it`, `expect`, and `vi`\nneed no import. `src/test-setup.ts` loads `@testing-library/jest-dom/vitest`, so\nits matchers are available everywhere. Run with `pnpm test`, or `pnpm test:watch`\nwhile iterating.\n\n## Layout\n\nTests are colocated and named `*.test.ts` / `*.test.tsx`, sitting beside the\nfile they cover: `src/app.tsx` → `src/app.test.tsx`.\n\n## Component tests\n\nTesting Library with `user-event`, querying by role and accessible name:\n\n```tsx\ndescribe('UserCard', () => {\n  it('should render the user name correctly', () => {\n    render(<UserCard name=\"Ada\" />);\n    expect(screen.getByRole('heading', { name: 'Ada' })).toBeInTheDocument();\n  });\n\n  it('should call onSelect when clicked', async () => {\n    const user = userEvent.setup();\n    const onSelect = vi.fn();\n    render(<UserCard name=\"Ada\" onSelect={onSelect} />);\n    await user.click(screen.getByRole('button', { name: 'Select' }));\n    expect(onSelect).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n- Interactions go through `userEvent.setup()` and `await user.click(...)`, not\n  `fireEvent`.\n- Handlers are `vi.fn()` asserted by call count, including the negative case —\n  a disabled control asserts `toHaveBeenCalledTimes(0)`.\n- Query by `getByRole` / `getByText`. Reach for `getByTestId` only when no\n  accessible query exists, such as a decorative spinner.\n- Assert on what the user observes, not on state or implementation details.\n\n## Naming\n\nTest names read `should <behaviour> correctly` or `should <effect> when\n<action>`. Group a unit's tests in one `describe` named for the unit.\n"
+		},
+		{
+			"path": "SKILL.md",
+			"contents": "---\nname: coding-standards\ndescription: Coding standards for this Vite + React + TypeScript app. Use when writing or changing components, hooks, utils, or tests, and before committing.\n---\n\n# Coding standards\n\nVite + React 19 + TypeScript, scaffolded with `create-chanom-app`. oxlint lints,\noxfmt formats, vitest tests. Read the reference for what you touch **before**\nwriting, so new code matches the code already here.\n\n## Which reference to load\n\n| You are writing…                             | Load                       |\n| -------------------------------------------- | -------------------------- |\n| Any `.ts` / `.tsx` file                      | `references/typescript.md` |\n| A component, hook, or anything rendering JSX | `references/react.md`      |\n| A `*.test.ts` / `*.test.tsx` file            | `references/vitest.md`     |\n\nThese layer: a new component with a test reads all three. Load every row that\napplies.\n\n## Universal rules\n\n- Filenames are kebab-case: `user-card.tsx`, `use-current-user.ts`, `format-date.ts`.\n- Before adding a file, open two neighbouring files of the same kind and match\n  their shape — import order, export style, test naming.\n- Source lives under `src/`. Colocate a test beside the code it covers:\n  `src/utils/format-date.ts` → `src/utils/format-date.test.ts`.\n\n## Verify\n\nAfter implementing, from the project root:\n\n```sh\npnpm lint\npnpm test\npnpm build\n```\n\nDone only when all three exit clean. On failure, fix and rerun until they do.\nRun `pnpm format` before committing. Comment- or doc-only changes may skip all\nfour.\n\n## Committing\n\nAsk before committing. Use conventional commits under 100 characters:\n`<type>(<scope>): <subject>`, e.g. `feat(auth): add sign-out button`. Scope is\nthe area you touched, not the repo name.\n"
+		}
+	]
+}];
+/** Directory holding the real skill files, agent-agnostic. */
+const SKILLS_ROOT = ".agents/skills";
+/** Directory Claude Code reads skills from; its entries are links into {@link SKILLS_ROOT}. */
+const CLAUDE_SKILLS_ROOT = ".claude/skills";
+/** Files a skill writes, rooted at `.agents/skills/<name>/`. */
+function skillFiles(skill) {
+	return skill.files.map((file) => ({
+		path: `${SKILLS_ROOT}/${skill.name}/${file.path}`,
+		contents: file.contents
+	}));
+}
+/**
+* The `.claude/skills/<name>` link for a skill. Real files live under
+* `.agents/skills/` so any agent tool can read them; Claude Code only looks in
+* `.claude/skills/`, so it gets a link rather than a second copy.
+*/
+function skillLink(skill) {
+	return {
+		path: `${CLAUDE_SKILLS_ROOT}/${skill.name}`,
+		target: `../../${SKILLS_ROOT}/${skill.name}`
+	};
+}
 //#endregion
 //#region src/bundled-versions.ts
 const bundledVersions = {
@@ -411,7 +455,7 @@ function commitMsgHook(pm) {
 }
 //#endregion
 //#region src/commands/add-commitlint/index.ts
-const apply$6 = Effect.fn("add-commitlint.apply")(function* (cwd, pm) {
+const apply$7 = Effect.fn("add-commitlint.apply")(function* (cwd, pm) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
@@ -433,7 +477,7 @@ function getPackages$4(pkg) {
 //#endregion
 //#region src/commands/add-husky/index.ts
 var HuskyInitFailed = class extends Data.TaggedError("HuskyInitFailed") {};
-const apply$5 = Effect.fn("add-husky.apply")(function* (cwd, pm) {
+const apply$6 = Effect.fn("add-husky.apply")(function* (cwd, pm) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
@@ -489,7 +533,7 @@ function getScriptPlan$2(scripts) {
 //#endregion
 //#region src/commands/add-knip/index.ts
 /** Returns a copy of `pkg` with missing scripts added; the caller owns writing package.json. */
-const apply$4 = Effect.fn("add-knip.apply")(function* (cwd, esm, pkg) {
+const apply$5 = Effect.fn("add-knip.apply")(function* (cwd, esm, pkg) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
@@ -526,7 +570,7 @@ function buildConfig(linters, formatters) {
 }
 //#endregion
 //#region src/commands/add-lint-staged/index.ts
-const apply$3 = Effect.fn("add-lint-staged.apply")(function* (cwd, linters = [], formatters = [], overwritePreCommit = false) {
+const apply$4 = Effect.fn("add-lint-staged.apply")(function* (cwd, linters = [], formatters = [], overwritePreCommit = false) {
 	if (linters.length === 0 && formatters.length === 0) {
 		yield* Effect.logDebug("no linters or formatters selected - skipping lint-staged setup");
 		return;
@@ -564,7 +608,7 @@ function getScriptPlan$1(scripts) {
 //#endregion
 //#region src/commands/add-oxfmt/index.ts
 /** Returns a copy of `pkg` with missing scripts added; the caller owns writing package.json. */
-const apply$2 = Effect.fn("add-oxfmt.apply")(function* (cwd, esm, pkg) {
+const apply$3 = Effect.fn("add-oxfmt.apply")(function* (cwd, esm, pkg) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
@@ -605,7 +649,7 @@ function getScriptPlan(scripts) {
 //#endregion
 //#region src/commands/add-oxlint/index.ts
 /** Returns a copy of `pkg` with missing scripts added; the caller owns writing package.json. */
-const apply$1 = Effect.fn("add-oxlint.apply")(function* (cwd, esm, pkg) {
+const apply$2 = Effect.fn("add-oxlint.apply")(function* (cwd, esm, pkg) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
@@ -623,6 +667,64 @@ const apply$1 = Effect.fn("add-oxlint.apply")(function* (cwd, esm, pkg) {
 	};
 });
 //#endregion
+//#region src/commands/add-skills/logic.ts
+/**
+* Splits the skill's files by whether they are already on disk. Existing files
+* always win: a user who has edited the standards to fit their project keeps
+* those edits, so re-running `chanom brew` is safe.
+*/
+function planSkillFiles(files, exists) {
+	const write = [];
+	const skipped = [];
+	for (const file of files) if (exists(file.path)) skipped.push(file.path);
+	else write.push(file);
+	return {
+		write,
+		skipped
+	};
+}
+//#endregion
+//#region src/commands/add-skills/index.ts
+/**
+* Links `.claude/skills/<name>` at the real directory under `.agents/skills/`.
+* Anything already at the link path - a link the user already has, or a real
+* directory they maintain by hand - is left alone and reported.
+*/
+const linkSkill = Effect.fn("add-skills.linkSkill")(function* (cwd, link) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const prompter = yield* Prompter;
+	const linkPath = path.join(cwd, link.path);
+	if (yield* fs.exists(linkPath)) {
+		yield* prompter.warn(`\`${link.path}\` already exists - skipping link`);
+		return;
+	}
+	yield* fs.makeDirectory(path.dirname(linkPath), { recursive: true });
+	yield* fs.symlink(link.target, linkPath);
+});
+/**
+* Writes every chanom skill into `.agents/skills/`, then links it into
+* `.claude/skills/`. Files already on disk are left untouched, so re-running is
+* safe. Contributes no packages and no scripts, so - like `add-vscode` - it
+* returns nothing for the caller to persist.
+*/
+const apply$1 = Effect.fn("add-skills.apply")(function* (cwd) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const prompter = yield* Prompter;
+	const files = SKILLS.flatMap(skillFiles);
+	const present = /* @__PURE__ */ new Set();
+	for (const file of files) if (yield* fs.exists(path.join(cwd, file.path))) present.add(file.path);
+	const plan = planSkillFiles(files, (filePath) => present.has(filePath));
+	for (const skipped of plan.skipped) yield* prompter.warn(`\`${skipped}\` already exists - skipping`);
+	for (const file of plan.write) {
+		const dest = path.join(cwd, file.path);
+		yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
+		yield* fs.writeFileString(dest, file.contents);
+	}
+	for (const skill of SKILLS) yield* linkSkill(cwd, skillLink(skill));
+});
+//#endregion
 //#region src/commands/add-vscode/index.ts
 const writeJson = Effect.fn("add-vscode.writeJson")(function* (filePath, value) {
 	yield* (yield* FileSystem.FileSystem).writeFileString(filePath, JSON.stringify(value, null, 2) + "\n");
@@ -785,6 +887,11 @@ const askRecipe = Effect.fn("brew.askRecipe")(function* () {
 					value: "vscode",
 					label: "vscode",
 					hint: "editor settings + extension recommendations"
+				},
+				{
+					value: "skills",
+					label: "skills",
+					hint: "coding standards for AI agents (.claude/skills)"
 				}
 			],
 			required: false
@@ -816,10 +923,11 @@ const installPackages = Effect.fn("brew.installPackages")(function* (pm, cwd, pa
 });
 const applyToppings = Effect.fn("brew.applyToppings")(function* (cwd, esm, pkg, toppings) {
 	let updated = pkg;
-	if (toppings.includes("oxlint")) updated = yield* apply$1(cwd, esm, updated);
-	if (toppings.includes("oxfmt")) updated = yield* apply$2(cwd, esm, updated);
-	if (toppings.includes("knip")) updated = yield* apply$4(cwd, esm, updated);
+	if (toppings.includes("oxlint")) updated = yield* apply$2(cwd, esm, updated);
+	if (toppings.includes("oxfmt")) updated = yield* apply$3(cwd, esm, updated);
+	if (toppings.includes("knip")) updated = yield* apply$5(cwd, esm, updated);
 	if (toppings.includes("vscode")) yield* apply(cwd, oxfmtConfigPath(esm));
+	if (toppings.includes("skills")) yield* apply$1(cwd);
 	return updated;
 });
 const persistScripts = Effect.fn("brew.persistScripts")(function* (pkgPath, pkg, updated) {
@@ -851,14 +959,14 @@ const setupCommitGate = Effect.fn("brew.setupCommitGate")(function* (cwd, pm, to
 	const path = yield* Path.Path;
 	const prompter = yield* Prompter;
 	const huskyExisted = yield* fs.exists(path.join(cwd, ".husky"));
-	yield* apply$5(cwd, pm);
-	if (wantsLintStaged(toppings)) yield* apply$3(cwd, selectedLinters(toppings), selectedFormatters(toppings), !huskyExisted);
+	yield* apply$6(cwd, pm);
+	if (wantsLintStaged(toppings)) yield* apply$4(cwd, selectedLinters(toppings), selectedFormatters(toppings), !huskyExisted);
 	else {
 		yield* prompter.warn("No linters or formatters selected - skipping lint-staged");
 		const seededHook = path.join(cwd, ".husky", "pre-commit");
 		if (!huskyExisted && (yield* fs.exists(seededHook))) yield* fs.remove(seededHook);
 	}
-	yield* apply$6(cwd, pm);
+	yield* apply$7(cwd, pm);
 });
 const commitChanges = Effect.fn("brew.commitChanges")(function* (cwd) {
 	const git = yield* Git;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanom/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "",
   "keywords": [],
   "repository": {