From a8e17df7fca21d05de9d20a1667ac68f8b809905 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Mon, 12 Oct 2026 18:05:25 +0900 Subject: [PATCH 1/3] docs: move agent instructions to AGENTS.md with turborepo agent rules Move the CLAUDE.md content into AGENTS.md and import it from CLAUDE.md via @AGENTS.md. Append the turbo-managed agent guidance block so newer turbo versions find it unchanged instead of leaving an uncommitted edit. --- AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 63 +--------------------------------------------- 2 files changed, 76 insertions(+), 62 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..85ffba0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,75 @@ + + +# @pleaseai/code-style + +Monorepo providing shared code style configurations for PleaseAI projects. + +## Tech Stack + +- Tool versions: mise (`mise.toml` pins node 24 + bun 1.3.14; `mise trust && mise install`) +- Package manager: bun (>=1.3.14) +- Build orchestration: Turborepo +- Module system: ESM only (`"type": "module"`) +- Node: >=22.0.0 +- TypeScript target: ES2022, moduleResolution: bundler + +## Packages + +| Package | Path | Build | +|---------|------|-------| +| `@pleaseai/eslint-config` | `packages/eslint-config` | tsdown | +| `@pleaseai/prettier-config` | `packages/perttier-config` | none (JSON only) | +| `@pleaseai/editorconfig` | `packages/editorconfig` | none (static file) | +| `@pleaseai/ast-grep-config` | `packages/ast-grep-config` | none (ast-grep YAML rules) | + +## Commands + +- `bun install` - Install dependencies +- `bun run build` - Build all packages via Turborepo +- `bun run lint` - Lint repo (dogfoods own eslint-config) +- `bun run lint:fix` - Lint with auto-fix + +## Architecture + +- `packages/eslint-config` wraps `@antfu/eslint-config` with PleaseAI defaults (2-space indent, single quotes, no semi) +- `packages/eslint-config/src/package-json.ts` exports `eslint-plugin-package-json` configs +- Root `eslint.config.ts` dogfoods `@pleaseai/eslint-config` +- `packages/ast-grep-config` holds the ADR-0022 (engineering-standards) layer-2 ast-grep rules in `rules//.yml` (each with a sibling `.md` README, rule tests in `rule-tests/`) and the layer-3 extraction rules in `extract/` (never in `ruleDirs`); `@ast-grep/cli` is a peer. Run `bun run test` in the package (`ast-grep test` + the e2e sgconfig test) +- `packages/cli/src/check/` is the `please-style check` path checker (layer 3). It resolves the `@ast-grep/cli` binary from the checked project first, then from the CLI's own install (`src/check/ast-grep.ts`), and the `extract/` rules from the CLI's own `@pleaseai/ast-grep-config` copy first (the project's copy is a last resort). `@pleaseai/ast-grep-config` is a regular `dependency` of the CLI; `@ast-grep/cli` is an optional peer of both packages (never a `dependency`, so installs do not download the native binary), installed explicitly only when the user selects the ast-grep tool. Tests live in `packages/cli/test/` mirroring `src/`, shared helpers in `test/test-utils/` (the CLI dogfoods its own rule) + +## Code Style + +- Follow @antfu/eslint-config conventions: no semicolons, single quotes, 2-space indent +- ESM imports only, no CommonJS + +## Release + +- Uses release-please (Google) for automated versioning and changelogs +- Config: `release-please-config.json` + `.release-please-manifest.json` +- Publishing: GitHub Actions workflow publishes to npm on release + +## Docs Site + +- Located at `docs/` — Docus (Nuxt) deployed to Cloudflare Pages +- Bun workspace member; build works because of `bunfig.toml` hoisted linker (see Gotchas) +- Build: `cd docs && bun run build` → outputs to `docs/dist/` +- Deploy: `cd docs && bun run deploy` (wrangler) +- ADR: `docs/adr/0001-choose-documentation-framework.md` + +## Gotchas + +- `packages/perttier-config` directory is intentionally(?) misspelled — do not rename without coordinating release-please config, CI workflows, and npm package name +- `bunfig.toml` sets `linker = "hoisted"` — required for Docus to build. Bun 1.3.2+ defaults to `isolated` linker in workspaces, which puts Docus's raw `.ts` server files under `.bun/` symlinks where Nitro's `rollup-plugin-inject` chokes on them. Hoisted linker (npm-style flat `node_modules`) avoids this. +- Docs build requires `mcp: { enabled: false }` in `docs/nuxt.config.ts` — `@nuxtjs/mcp-toolkit` imports `agents/mcp` (Cloudflare Workers AI Agents) which breaks the `cloudflare_pages` preset. +- Docus `cloudflare_pages` preset outputs to `dist/`, not `.output/public/` — `wrangler.jsonc` `pages_build_output_dir` must match. + + + +# This is NOT the Turborepo you know + +Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`. + +Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access. + +This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation. + diff --git a/CLAUDE.md b/CLAUDE.md index 23b47f8..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,62 +1 @@ -# @pleaseai/code-style - -Monorepo providing shared code style configurations for PleaseAI projects. - -## Tech Stack - -- Tool versions: mise (`mise.toml` pins node 24 + bun 1.3.14; `mise trust && mise install`) -- Package manager: bun (>=1.3.14) -- Build orchestration: Turborepo -- Module system: ESM only (`"type": "module"`) -- Node: >=22.0.0 -- TypeScript target: ES2022, moduleResolution: bundler - -## Packages - -| Package | Path | Build | -|---------|------|-------| -| `@pleaseai/eslint-config` | `packages/eslint-config` | tsdown | -| `@pleaseai/prettier-config` | `packages/perttier-config` | none (JSON only) | -| `@pleaseai/editorconfig` | `packages/editorconfig` | none (static file) | -| `@pleaseai/ast-grep-config` | `packages/ast-grep-config` | none (ast-grep YAML rules) | - -## Commands - -- `bun install` - Install dependencies -- `bun run build` - Build all packages via Turborepo -- `bun run lint` - Lint repo (dogfoods own eslint-config) -- `bun run lint:fix` - Lint with auto-fix - -## Architecture - -- `packages/eslint-config` wraps `@antfu/eslint-config` with PleaseAI defaults (2-space indent, single quotes, no semi) -- `packages/eslint-config/src/package-json.ts` exports `eslint-plugin-package-json` configs -- Root `eslint.config.ts` dogfoods `@pleaseai/eslint-config` -- `packages/ast-grep-config` holds the ADR-0022 (engineering-standards) layer-2 ast-grep rules in `rules//.yml` (each with a sibling `.md` README, rule tests in `rule-tests/`) and the layer-3 extraction rules in `extract/` (never in `ruleDirs`); `@ast-grep/cli` is a peer. Run `bun run test` in the package (`ast-grep test` + the e2e sgconfig test) -- `packages/cli/src/check/` is the `please-style check` path checker (layer 3). It resolves the `@ast-grep/cli` binary from the checked project first, then from the CLI's own install (`src/check/ast-grep.ts`), and the `extract/` rules from the CLI's own `@pleaseai/ast-grep-config` copy first (the project's copy is a last resort). `@pleaseai/ast-grep-config` is a regular `dependency` of the CLI; `@ast-grep/cli` is an optional peer of both packages (never a `dependency`, so installs do not download the native binary), installed explicitly only when the user selects the ast-grep tool. Tests live in `packages/cli/test/` mirroring `src/`, shared helpers in `test/test-utils/` (the CLI dogfoods its own rule) - -## Code Style - -- Follow @antfu/eslint-config conventions: no semicolons, single quotes, 2-space indent -- ESM imports only, no CommonJS - -## Release - -- Uses release-please (Google) for automated versioning and changelogs -- Config: `release-please-config.json` + `.release-please-manifest.json` -- Publishing: GitHub Actions workflow publishes to npm on release - -## Docs Site - -- Located at `docs/` — Docus (Nuxt) deployed to Cloudflare Pages -- Bun workspace member; build works because of `bunfig.toml` hoisted linker (see Gotchas) -- Build: `cd docs && bun run build` → outputs to `docs/dist/` -- Deploy: `cd docs && bun run deploy` (wrangler) -- ADR: `docs/adr/0001-choose-documentation-framework.md` - -## Gotchas - -- `packages/perttier-config` directory is intentionally(?) misspelled — do not rename without coordinating release-please config, CI workflows, and npm package name -- `bunfig.toml` sets `linker = "hoisted"` — required for Docus to build. Bun 1.3.2+ defaults to `isolated` linker in workspaces, which puts Docus's raw `.ts` server files under `.bun/` symlinks where Nitro's `rollup-plugin-inject` chokes on them. Hoisted linker (npm-style flat `node_modules`) avoids this. -- Docs build requires `mcp: { enabled: false }` in `docs/nuxt.config.ts` — `@nuxtjs/mcp-toolkit` imports `agents/mcp` (Cloudflare Workers AI Agents) which breaks the `cloudflare_pages` preset. -- Docus `cloudflare_pages` preset outputs to `dist/`, not `.output/public/` — `wrangler.jsonc` `pages_build_output_dir` must match. +@AGENTS.md From f2a02247599feef67dfec24c90fb5e54ae1dea85 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Mon, 12 Oct 2026 18:12:25 +0900 Subject: [PATCH 2/3] chore(deps): bump turbo to ^2.11.7 2.11 bundles its docs/ in the package, which the turborepo agent rules block in AGENTS.md tells agents to read. --- bun.lock | 16 ++++++++-------- package.json | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/bun.lock b/bun.lock index 03e489b..fcd185b 100644 --- a/bun.lock +++ b/bun.lock @@ -11,7 +11,7 @@ "eslint": "^10.0.3", "husky": "^9.1.7", "lint-staged": "^17.6.0", - "turbo": "^2.0.0", + "turbo": "^2.11.7", "typescript": "^6.0.2", }, }, @@ -995,17 +995,17 @@ "@tiptap/y-tiptap": ["@tiptap/y-tiptap@3.0.2", "", { "dependencies": { "lib0": "^0.2.100" }, "peerDependencies": { "prosemirror-model": "^1.7.1", "prosemirror-state": "^1.2.3", "prosemirror-view": "^1.9.10", "y-protocols": "^1.0.1", "yjs": "^13.5.38" } }, "sha512-flMn/YW6zTbc6cvDaUPh/NfLRTXDIqgpBUkYzM74KA1snqQwhOMjnRcnpu4hDFrTnPO6QGzr99vRyXEA7M44WA=="], - "@turbo/darwin-64": ["@turbo/darwin-64@2.9.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-qPxhKsLMQP+9+dsmPgAGidi5uNifD4AoAOnEnljab3Qgn0QZRR31Hp+/CgW3Ia5AanWj6JuLLTBYvuQj4mqTWg=="], + "@turbo/darwin-64": ["@turbo/darwin-64@2.11.7", "", { "os": "darwin", "cpu": "x64" }, "sha512-Z2LFOxwbiJueD1miByXJS/BrW21vv6YaQXZustty5jEX4vQYw6zyh101Sz1QO7WG0mqBzKagZ/DoAeeujI0/Sw=="], - "@turbo/darwin-arm64": ["@turbo/darwin-arm64@2.9.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-vkF/9F/l3aWd4bHxTui5Hh0F5xrTZ4e3rbBsc57zA6O8gNbmHN3B6eZ5psAIP2CnJRZ8ZxRjV3WZHeNXMXkPBw=="], + "@turbo/darwin-arm64": ["@turbo/darwin-arm64@2.11.7", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Vhv8ybgIflosNDSSRD9fNXHlCFA60dsGyTqQmc7l28SEX5jOaweCCD4BBYNd8/p0WGkw3e7tZbfA9w6FsujGvw=="], - "@turbo/linux-64": ["@turbo/linux-64@2.9.5", "", { "os": "linux", "cpu": "x64" }, "sha512-z/Get5NUaUxm5HSGFqVMICDRjFNsCUhSc4wnFa/PP1QD0NXCjr7bu9a2EM6md/KMCBW0Qe393Ac+UM7/ryDDTw=="], + "@turbo/linux-64": ["@turbo/linux-64@2.11.7", "", { "os": [ "linux", "android", ], "cpu": "x64" }, "sha512-rAqRp3blQKk1+ylMGlZHAW0eJjVNuuGUm4ZrC6RU1Im8tLryvaO4a2zLQ/FQi1TRlmKqKV9YXBki2YeytlLbXA=="], - "@turbo/linux-arm64": ["@turbo/linux-arm64@2.9.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-jyBifaNoI5/NheyswomiZXJvjdAdvT7hDRYzQ4meP0DKGvpXUjnqsD+4/J2YSDQ34OHxFkL30FnSCUIVOh2PHw=="], + "@turbo/linux-arm64": ["@turbo/linux-arm64@2.11.7", "", { "os": [ "linux", "android", ], "cpu": "arm64" }, "sha512-thVYGov7S+llXAxrl3kBb/efalav0xhrjl5NHCR6AfKx14JkbqaetvbVwyss4FvZ9rt+Pv3xsTb+8SIYix8DTg=="], - "@turbo/windows-64": ["@turbo/windows-64@2.9.5", "", { "os": "win32", "cpu": "x64" }, "sha512-ph24K5uPtvo7UfuyDXnBiB/8XvrO+RQWbbw5zkA/bVNoy9HDiNoIJJj3s62MxT9tjEb6DnPje5PXSz1UR7QAyg=="], + "@turbo/windows-64": ["@turbo/windows-64@2.11.7", "", { "os": "win32", "cpu": "x64" }, "sha512-ZIoKT7J7KutgYl4bGxmmgeUQjG+7E0nY8BF9dxUOiMH2vdTsM4JQ2uSwTYFkTR2Llbg6ghGjSmuZ8LQtkLEYjg=="], - "@turbo/windows-arm64": ["@turbo/windows-arm64@2.9.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-6c5RccT/+iR39SdT1G5HyZaD2n57W77o+l0TTfxG/cVlhV94Acyg2gTQW7zUOhW1BeQpBjHzu9x8yVBZwrHh7g=="], + "@turbo/windows-arm64": ["@turbo/windows-arm64@2.11.7", "", { "os": "win32", "cpu": "arm64" }, "sha512-88Xv2f7SLGVJ68lRRx8o375dKmnZYNdDtvlKcPA0kZpcF93eAQd8l96BKQ0/AMHG0bMJA0Z5QqoqtetxzNsC+g=="], "@tybys/wasm-util": ["@tybys/wasm-util@0.10.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg=="], @@ -2763,7 +2763,7 @@ "tunnel-agent": ["tunnel-agent@0.6.0", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w=="], - "turbo": ["turbo@2.9.5", "", { "optionalDependencies": { "@turbo/darwin-64": "2.9.5", "@turbo/darwin-arm64": "2.9.5", "@turbo/linux-64": "2.9.5", "@turbo/linux-arm64": "2.9.5", "@turbo/windows-64": "2.9.5", "@turbo/windows-arm64": "2.9.5" }, "bin": { "turbo": "bin/turbo" } }, "sha512-JXNkRe6H6MjSlk5UQRTjyoKX5YN2zlc2632xcSlSFBao5yvbMWTpv9SNolOZlZmUlcDOHuszPLItbKrvcXnnZA=="], + "turbo": ["turbo@2.11.7", "", { "optionalDependencies": { "@turbo/darwin-64": "2.11.7", "@turbo/darwin-arm64": "2.11.7", "@turbo/linux-64": "2.11.7", "@turbo/linux-arm64": "2.11.7", "@turbo/windows-64": "2.11.7", "@turbo/windows-arm64": "2.11.7" }, "bin": { "turbo": "bin/turbo" } }, "sha512-RhXHbqfvY6o3xt/zSHCwSNwLrZlXiqHzewi4eAj9PtZ1T1CqgMJ2yIDb7SKPTG9IikTm925mfzL6hldQVdyNWw=="], "type-check": ["type-check@0.4.0", "", { "dependencies": { "prelude-ls": "^1.2.1" } }, "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew=="], diff --git a/package.json b/package.json index fba2689..c4eb9b6 100644 --- a/package.json +++ b/package.json @@ -40,7 +40,7 @@ "eslint": "^10.0.3", "husky": "^9.1.7", "lint-staged": "^17.6.0", - "turbo": "^2.0.0", + "turbo": "^2.11.7", "typescript": "^6.0.2" }, "lint-staged": { From a71f43293be6fce3315e3ef3d74a78c32215a28b Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Mon, 12 Oct 2026 18:28:50 +0900 Subject: [PATCH 3/3] chore: apply AI code review suggestions Add the missing @pleaseai/code-style (packages/cli) row to the Packages table in AGENTS.md. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 85ffba0..fb573ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ Monorepo providing shared code style configurations for PleaseAI projects. | Package | Path | Build | |---------|------|-------| +| `@pleaseai/code-style` | `packages/cli` | tsdown | | `@pleaseai/eslint-config` | `packages/eslint-config` | tsdown | | `@pleaseai/prettier-config` | `packages/perttier-config` | none (JSON only) | | `@pleaseai/editorconfig` | `packages/editorconfig` | none (static file) |