📏 @sha3/code-standards

Scaffold TypeScript projects + enforce how AI writes code.

TL;DR

If you just want to start now:

npx @sha3/code-standards init --template node-service --yes

If your project was already scaffolded and you updated this package:

npx @sha3/code-standards refresh

Then in your AI chat, paste this:

Before writing code:
1) Read AGENTS.md and ai/<assistant>.md in this repo.
2) List the blocking rules you will follow.
3) Implement the task following those rules.
4) Run npm run check and fix all issues.
5) Return changed files and which AGENTS rules were applied.

profile is optional. Use it only when you want to customize AI behavior.

What This Tool Actually Does

This package combines 3 things in one:

1. Project scaffolding (init) for node-lib and node-service.
2. Shared tooling exports (eslint, prettier, tsconfig).
3. AI behavior contract generation (AGENTS.md + ai/*.md) based on a style profile.

So it is not only formatting/linting. It also defines how AI should think and generate code.

Default generated contract includes structural class/file blocks such as:

• imports:externals
• imports:internals
• consts
• types
• private:attributes
• protected:attributes
• private:properties
• public:properties
• constructor
• static:properties
• factory
• private:methods
• protected:methods
• public:methods
• static:methods

Section marker format is fixed to:

• /**
• * @section <block-name>
• */

All blocks MUST exist even when empty (// empty).

Additional blocking defaults:

• Max line length is 160 chars, and lines should stay on one line when they fit.
• if/else/loop statements MUST always use braces.
• README updates MUST follow a top-tier quality standard (see standards/readme.md).

Do I Need profile First?

No.

• If you run init without profile flags, it uses the bundled default profile.
• If you want your custom coding preferences, create a profile and pass it to init.

Default flow (no profile setup):

npx @sha3/code-standards init --template node-service --yes

Custom profile flow:

npx @sha3/code-standards profile --profile ./profiles/team.profile.json
npx @sha3/code-standards init --template node-service --yes --profile ./profiles/team.profile.json

What Happens After init

After init, your new repo contains:

• AGENTS.md (blocking rules for AI)
• ai/codex.md, ai/cursor.md, ai/copilot.md, ai/windsurf.md
• ai/examples/rules/*.ts (good/bad examples per rule)
• ai/examples/demo/src/* (feature-folder demo with classes and section blocks)
• src/config.ts for centralized hardcoded configuration values
• README.md generated with an icon emoji and complete integration docs (API + config + integration contract for other LLMs)
• .gitignore preconfigured for Node/TypeScript output
• .vscode/settings.json + .vscode/extensions.json for autoformat-on-save and eslint autofix-on-save in VS Code
• lint/format/typecheck/test-ready project template
• package.json.codeStandards metadata used by refresh (template, profilePath, withAiAdapters, lastRefreshWith)

config.ts convention: export a single default object and import it as import CONFIG from "./config.ts".

That means the next step is not configuring tools. The next step is telling your assistant to obey AGENTS.md before coding.

Generated project code is TypeScript-only: implementation and tests live in .ts files.

TypeScript Example Files

init now stores code examples in .ts files instead of embedding them inside AGENTS.md.

Demo structure generated by default:

• ai/examples/demo/src/config.ts
• ai/examples/demo/src/invoices/invoice-service.ts
• ai/examples/demo/src/invoices/invoice-errors.ts
• ai/examples/demo/src/invoices/invoice-types.ts
• ai/examples/demo/src/billing/billing-service.ts

Rule-specific examples:

• ai/examples/rules/class-first-good.ts
• ai/examples/rules/class-first-bad.ts
• ai/examples/rules/constructor-good.ts
• ai/examples/rules/constructor-bad.ts
• ai/examples/rules/functions-good.ts
• ai/examples/rules/functions-bad.ts
• ai/examples/rules/returns-good.ts
• ai/examples/rules/returns-bad.ts
• ai/examples/rules/async-good.ts
• ai/examples/rules/async-bad.ts
• ai/examples/rules/control-flow-good.ts
• ai/examples/rules/control-flow-bad.ts
• ai/examples/rules/errors-good.ts
• ai/examples/rules/errors-bad.ts
• ai/examples/rules/testing-good.ts
• ai/examples/rules/testing-bad.ts

How To Use With AI (Copy/Paste)

Universal bootstrap prompt

Use this as your first message in any coding session:

Before generating code:
- Read AGENTS.md and ai/<assistant>.md.
- Summarize the blocking rules you must follow.
- Implement the task with those rules.
- Run npm run check and fix issues until it passes.
- Return changed files + a short compliance checklist.

Task prompt template

Task: <describe task>
Constraints:
- Follow AGENTS.md and ai/<assistant>.md strictly.
- Keep architecture and naming conventions intact.
- Add/update tests for behavior changes.
- Run npm run check at the end.
Output:
- What changed
- Why
- Proof checks passed

Replace <assistant> with:

• codex
• cursor
• copilot
• windsurf

Assistant-Specific Start Commands

Use these prompts depending on tool:

Codex

Read AGENTS.md and ai/codex.md first. Do not start implementation until you summarize blocking rules.

Cursor

Read AGENTS.md and ai/cursor.md. Enforce rules while implementing and keep edits compliant.

GitHub Copilot Chat

Use AGENTS.md and ai/copilot.md as mandatory coding rules for this task.

Windsurf

Read AGENTS.md and ai/windsurf.md and treat them as non-negotiable constraints.

Quick Start (Step by Step)

1) Create profile (optional)

npx @sha3/code-standards profile

Non-interactive:

npx @sha3/code-standards profile \
  --non-interactive \
  --profile ./profiles/team.profile.json \
  --force-profile

2) Scaffold project

Run this inside the directory you want to initialize.

npx @sha3/code-standards init --template node-service --yes

Without --yes, init prompts for:

• npm package name
• GitHub repository URL

With explicit profile:

npx @sha3/code-standards init \
  --template node-lib \
  --yes \
  --no-install \
  --profile ./profiles/team.profile.json

Skip AI files when needed:

npx @sha3/code-standards init --template node-lib --yes --no-ai-adapters

3) Work loop inside generated project

npm install
npm run check

Then use the prompts above in your AI tool.

4) Sync updates from @sha3/code-standards

Run this inside an already scaffolded project:

npx @sha3/code-standards refresh

refresh default behavior:

• scope Managed + AI (package.json, config files, AGENTS.md, ai/*, ai/examples/*)
• non-destructive for project source code (src/**, test/** are preserved)
• auto-detect template (or force with --template)
• selective merge for package.json (managed scripts/devDependencies updated, custom keys preserved)
• runs npm run fix and npm run check automatically after refreshing files
• prints a ready-to-paste LLM prompt to reprocess updated conventions across the repository
• no dependency install unless --install (use --install if dependencies are missing before auto-check)

CLI Reference

code-standards <command> [options]

Commands:
  init                  Initialize a project in the current directory
  refresh               Re-apply managed standards files and AI instructions
  update                Alias of refresh
  profile               Create or update the AI style profile

init options

init always uses the current working directory as target. An existing .git/ directory is allowed without --force.

• --template <node-lib|node-service>
• --package-name <name>
• --repository-url <url>
• --yes
• --no-install
• --force
• --with-ai-adapters
• --no-ai-adapters
• --profile <path>

refresh options

refresh always uses the current working directory as target.

• --template <node-lib|node-service>
• --package-name <name>
• --repository-url <url>
• --profile <path>
• --with-ai-adapters
• --no-ai-adapters
• --dry-run
• --install
• --yes

profile options

• --profile <path>
• --non-interactive
• --force-profile

Package Exports

ESLint

// eslint.config.mjs
import nodeConfig from "@sha3/code-standards/eslint/node";
import testConfig from "@sha3/code-standards/eslint/test";

export default [...nodeConfig, ...testConfig];

Prettier

// prettier.config.cjs
module.exports = require("@sha3/code-standards/prettier");

TSConfig

{ "extends": "@sha3/code-standards/tsconfig/node-lib.json" }

Local Quality Gates

Main gate:

npm run check

Includes:

• standards schema validation
• profile schema validation
• lint
• format check
• typecheck
• smoke tests + CLI tests

Other scripts:

• npm run fix
• npm run standards:validate
• npm run profile:validate
• npm run release:check
• npm run release:publish -- --dry-run
• npm run release:publish
• npm run hooks:install

FAQ

“I ran init. How do I force AI to follow rules?”

Always start with a bootstrap prompt that says:

1. read AGENTS.md and ai/<assistant>.md
2. summarize blocking rules
3. implement
4. run npm run check

“AI ignored my standards.”

Use stricter prompt wording:

Treat AGENTS.md as hard constraints. If any rule conflicts with your default behavior, AGENTS.md wins.
If existing repository code conflicts with AGENTS.md, AGENTS.md and `@sha3/code-standards` conventions still win.
Do not modify `@sha3/code-standards` managed files (`AGENTS.md`, `ai/*`, `ai/examples/*`, tooling configs) unless explicitly requested.

“Windsurf shows rvest.vs-code-prettier-eslint errors.”

Disable or uninstall rvest.vs-code-prettier-eslint in that workspace.
Use only:

• esbenp.prettier-vscode
• dbaeumer.vscode-eslint

The rvest extension is not compatible with ESLint 9 flat config.

“Do I need to repeat the rules every task?”

Yes, practically you should restate that AGENTS is mandatory at each task boundary. Keep the prompt short and consistent.

“Can I use this without AI files?”

Yes, with --no-ai-adapters. You still get scaffold + tooling exports.

Repository Layout

.
├── bin/                # CLI entrypoint
├── profiles/           # AI style profile schema + defaults
├── resources/ai/       # templates for generated AGENTS/adapters
├── standards/          # canonical standards docs + manifest/schema
├── templates/          # project scaffolds (node-lib, node-service)
├── eslint/             # exported eslint configs
├── prettier/           # exported prettier config
└── tsconfig/           # exported tsconfig presets

Publishing

npm run release:check
npm run release:publish

release:publish behavior:

• validates quality gates (unless --skip-checks)
• checks npm registry for package.json current version
• if current version already exists on npm: runs npm version minor --no-git-tag-version automatically
• if current version does not exist on npm: keeps your manual version as-is