@sha3/code

Scaffold TypeScript projects, rebuild them with refactor, and enforce repository policy with verify.

TL;DR

Create a new project:

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

Realign an existing repo:

npx @sha3/code refactor --yes

Run verification for humans:

npx @sha3/code verify

Run verification for automation:

npx @sha3/code verify --report json

Explain a deterministic rule:

npx @sha3/code verify --explain single-return

Installation

Use it directly with npx:

npx @sha3/code --help

Or install it in a repo:

npm install -D @sha3/code

Compatibility

• Node.js 20.11+
• ESM package runtime
• TypeScript-first projects
• Biome as the baseline formatter and linter

What It Does

@sha3/code manages 3 different concerns:

• init: creates a standards-managed TypeScript scaffold
• refactor: snapshots an existing repo and rebuilds it onto the managed scaffold
• verify: enforces repository policy that generic tooling does not cover well

That last part matters: verify is not another formatter or typechecker. It is the package-specific policy engine for generated repos. Generated scaffolds are also expected to ship package-grade README files rather than placeholder docs.

Non-Negotiables

Simplicity is mandatory.

• choose the simplest correct implementation for the current requirement
• avoid speculative abstractions, helper layers, wrappers, and extension points without immediate need
• if two solutions are both correct, prefer the smaller and more direct one
• do not remove valid responsibility boundaries in the name of simplicity
• simplicity means avoiding gratuitous complexity, not reducing structure blindly
• let Biome decide final wrapping; prefer compact code, but do not force single-line layouts that the formatter keeps multiline

Public API

CLI commands

code-standards init
code-standards refactor
code-standards profile
code-standards verify

Package exports

@sha3/code/biome
@sha3/code/tsconfig/base.json
@sha3/code/tsconfig/node-lib.json
@sha3/code/tsconfig/node-service.json

verify options

code-standards verify [--report text|json] [--only <rule-id[,rule-id...]>] [--files <path[,path...]>] [--strict]
code-standards verify --explain <rule-id>

Behavior notes:

• init always works in the current directory and creates a fresh scaffold.
• refactor always works in the current directory and never accepts a remote or local source argument.
• refactor snapshots the previous repo state under .code-standards/refactor-source/ before rebuilding managed files.
• verify is the project-policy checker. It complements Biome and TypeScript instead of replacing them.
• verify --report json is intended for CI, PR automation, and scripts.
• default verify fails only on error severity; --strict also fails on warning.
• verify --explain <rule-id> prints operational documentation for a rule without checking the repo.
• code-standards verify --help prints the same option surface shown above.

What verify checks

verify covers project policy that is specific to @sha3/code, including:

• contract presence and validity for AGENTS.md and ai/contract.json
• metadata sync between package.json.codeStandards and ai/contract.json
• required managed files from the active template
• required README sections
• README documentation for public exports and public class methods
• HTTP API documentation for service templates
• TypeScript-only source policy in src/ and test/
• deterministic AST rules such as single-return, async-await-only, canonical-config-import, and file naming rules
• single-return stays strict in src/ except for src/http/**, where transport handlers may use early returns when that keeps request flow clearer

What verify does not check

verify does not replace the generic toolchain:

• formatting, line wrapping, and generic lint rules stay in Biome
• type correctness stays in TypeScript
• runtime behavior stays in tests

When to use verify

Use the tools together, not interchangeably:

• run Biome when you want style, formatting, and baseline lint feedback
• run TypeScript when you want type-safety feedback
• run verify when you want to enforce repository contract, scaffold integrity, and project-policy rules

Integration Guide

Create a new project

mkdir my-service
cd my-service
npx @sha3/code init --template node-service --yes

init step by step

Use init when you are starting a new repo from the managed scaffold.

1. Create and enter the target directory.
2. Run init with the template you want.
3. Review the generated contract files before asking an LLM to write code.
4. Fill PROMPT.md and give only that file to the LLM.
5. Make the LLM execute npm run check itself and fix any failures before it finishes.

Minimal flow:

mkdir my-service
cd my-service
npx @sha3/code init --template node-service --yes

What init generates for you:

• AGENTS.md as the repo policy entrypoint
• SKILLS.md as the index of specialized workflows that should only be loaded when relevant
• ai/contract.json as the deterministic standards contract
• ai/rules.md as the concise human-readable implementation rules file for the LLM
• skills/* workflow guides such as init, refactor, feature shaping, simplicity audit, change synchronization, test scope selection, HTTP API conventions, and README authoring
• ai/<assistant>.md adapter files when AI adapters are enabled
• PROMPT.md in the project root as the single user-authored request file and LLM entrypoint
• prompts/init.prompt.md, prompts/init-phase-2-implement.md, and prompts/init-phase-3-verify.md as internal workflow prompts the LLM should load by itself
• the managed src/, test/, config, and package surface for the selected template
• a README scaffold that is meant to be rewritten into package-grade integration documentation once real behavior exists
• a root SCAFFOLD-FEEDBACK.md handoff requirement in the generated workflow so the LLM leaves scaffold/process feedback after implementation

The CLI also prints the minimal next step after init, so the user does not have to infer the LLM workflow manually.

Recommended LLM workflow after init:

1. Open PROMPT.md.
2. Complete the final User Request section.
3. Paste only PROMPT.md into the LLM.
4. Let the LLM read prompts/init.prompt.md, prompts/init-phase-2-implement.md, and prompts/init-phase-3-verify.md by itself.
5. Let the LLM load optional skills only when the workflow actually triggers them.

Minimal request example for PROMPT.md:

Task:
- Build the first HTTP endpoint for service health.
- Keep the generated scaffold structure intact.
- Add tests for the new behavior.

The final phase must explicitly require the LLM to execute:

npm run check

The final phase must also require the LLM to fix any failing checks, rewrite README.md when behavior changes, and create or update SCAFFOLD-FEEDBACK.md.

Regenerate an existing repo

Run this from the project root:

npx @sha3/code refactor --yes

refactor will:

1. analyze the current repository
2. capture preservation decisions
3. write .code-standards/refactor-source/latest/
4. write public-contract.json, preservation.json, and analysis-summary.md
5. rebuild the managed scaffold
6. generate the LLM workflow pack, with PROMPT.md as the single user entrypoint

refactor step by step

Use refactor when you already have a repo and want to rebuild it onto the managed scaffold without losing the contracts you choose to preserve.

1. Go to the root of the existing project.
2. Run refactor.
3. Answer the preservation questions if you are in interactive mode.
4. Let the command move the legacy code into .code-standards/refactor-source/latest/ and rebuild the managed surface.
5. Open PROMPT.md and complete the request section.
6. Paste only PROMPT.md into the LLM and let it load the refactor artifacts and phase prompts itself.
7. Require the LLM to execute npm run check itself and fix any failures before it finishes.
8. Require the LLM to finish by creating or updating SCAFFOLD-FEEDBACK.md with concrete scaffold/process feedback.

Typical command:

npx @sha3/code refactor --yes

If you want dependencies installed as part of the run:

npx @sha3/code refactor --yes --install

After refactor, these files matter most:

• PROMPT.md
• AGENTS.md
• SKILLS.md
• skills/feature-shaping/SKILL.md
• skills/simplicity-audit/SKILL.md
• skills/change-synchronization/SKILL.md
• skills/test-scope-selection/SKILL.md
• skills/http-api-conventions/SKILL.md
• ai/contract.json
• ai/rules.md
• skills/refactor-workflow/SKILL.md
• .code-standards/refactor-source/public-contract.json
• .code-standards/refactor-source/preservation.json
• .code-standards/refactor-source/analysis-summary.md
• .code-standards/refactor-source/latest/
• prompts/refactor.prompt.md
• prompts/refactor-phase-2-rebuild.md
• prompts/refactor-phase-3-verify.md

The CLI prints the single LLM entry file after refactor completes. The normal flow is: run refactor, complete PROMPT.md, and give only that file to the LLM.

Important behavior note:

• refactor does not run npm run fix or npm run check against the intermediate refactor state.
• refactor does not run the final npm run check against the pre-refactor codebase.
• The old implementation is moved to .code-standards/refactor-source/latest/ as reference material.
• The final validation belongs to the rewritten src/ and test/ produced after the LLM handoff.

Recommended LLM workflow after refactor:

1. Run refactor and wait for it to complete.
2. Open PROMPT.md and complete the User Request section.
3. Paste only PROMPT.md into the LLM.
4. Let the LLM read prompts/refactor.prompt.md, prompts/refactor-phase-2-rebuild.md, and prompts/refactor-phase-3-verify.md by itself.
5. Let the LLM rebuild, verify, and close the task end to end.

Minimal request example for PROMPT.md:

Task:
- Rebuild the application behavior inside the fresh scaffold under src/ and test/.
- Preserve the public API and HTTP contracts captured in the refactor artifacts.
- Do not edit managed files unless a standards update is explicitly required.

6. Make the final phase rewrite README.md as package-grade integration documentation for the rebuilt public API and runtime behavior when needed.
7. In the final phase, explicitly require the LLM to execute:

npm run check

8. Require the LLM to fix any failing checks and rerun the command until it passes.

Practical rule: refactor prepares the repo and the context pack; the user only fills PROMPT.md, and the LLM consumes the rest of the workflow pack autonomously.

Verify a project

Human-readable verification:

npx @sha3/code verify

Machine-readable verification:

npx @sha3/code verify --report json

Focused verification by rule:

npx @sha3/code verify --only single-return,canonical-config-import

Focused verification by files:

npx @sha3/code verify --files src/user/user.service.ts,test/user.test.ts

Strict verification:

npx @sha3/code verify --strict

Combined scope control:

npx @sha3/code verify --report json --only single-return --files src/user/user.service.ts

Rule explanation:

npx @sha3/code verify --explain single-return

verify is the command generated projects use behind npm run standards:check.

Configuration

Generated projects centralize runtime constants in src/config.ts.

This package centralizes standards through:

• standards/manifest.json as the canonical standards manifest
• profiles/default.profile.json as the default AI profile
• biome.json as the shared Biome config export

Profile-driven behavior can be customized with:

npx @sha3/code profile --profile ./profiles/team.profile.json

Then applied during init or refactor with --profile.

Scripts

Repository-level scripts:

• npm run check: standards validation, profile validation, AI resource validation, Biome lint, Biome format check, typecheck, tests
• npm run fix: Biome write + format write
• npm run lint: biome check .
• npm run format:check: biome format .
• npm run typecheck: TypeScript validation
• npm run test: smoke fixtures plus Node test runner

Generated project scripts:

• npm run standards:check: code-standards verify
• npm run check: standards + lint + format + typecheck + tests
• npm run fix: Biome autofix + format write

Structure

Key repository paths:

• bin/code-standards.mjs: CLI entrypoint
• lib/cli/run-init.mjs: project initialization flow
• lib/cli/run-refactor.mjs: in-place refactor flow
• lib/cli/run-verify.mjs: deterministic verification flow
• lib/verify/: issue model, explain mode, renderers, project checks, and AST-level source rules
• templates/: node-lib and node-service managed scaffolds
• prompts/: starter prompts for init and refactor
• resources/ai/: AI contract templates, adapters, examples, and rule catalog

Troubleshooting

biome: command not found

Install dependencies in the current workspace:

npm install

refactor says package.json was not found

Run code-standards refactor from the root of the target project.

Verify Modes

verify has 5 useful modes:

• default text mode: human-readable errors to stderr
• --report json: structured output to stdout
• --only: execute only selected rule ids
• --files: limit file-oriented checks to a subset of files
• --strict: fail on warnings as well as errors
• --explain: print documentation for one rule instead of verifying the repo

Important behavior:

• project-wide contract checks still run even when --files is used
• file-oriented checks such as AST source rules and TypeScript-only checks are scoped by --files
• --explain cannot be combined with --report, --only, or --files
• text remains the default output mode to preserve human-friendly local usage

Verify Output

Example text output:

- ERROR [single-return] src/user/user.service.ts: functions and methods outside src/http/ must use a single return statement
- WARNING [large-class-heuristic/heuristic] src/user/user.service.ts: very large classes should be decomposed into smaller cohesive units
Verification failed with 1 error(s) and 1 warning(s).

Example JSON output:

{
  "ok": false,
  "hasWarnings": true,
  "issues": [
    {
      "ruleId": "single-return",
      "category": "source-rule",
      "severity": "error",
      "message": "functions and methods outside src/http/ must use a single return statement",
      "relativePath": "src/user/user.service.ts",
      "enforcedBy": "verify"
    }
  ],
  "summary": {
    "issueCount": 1,
    "errorCount": 1,
    "warningCount": 0,
    "auditCount": 0,
    "checkedRuleIds": ["single-return"],
    "checkedFiles": ["src/user/user.service.ts"]
  }
}

Exit code behavior:

• exit code 0: verification passed at the requested severity threshold
• exit code non-zero: verification found blocking severities for the current mode or arguments were invalid

Using verify in CI

Save a structured report:

npx @sha3/code verify --report json > verify-report.json

Fail a script based on the result:

node -e 'const fs=require("node:fs"); const report=JSON.parse(fs.readFileSync("verify-report.json","utf8")); if(!report.ok) process.exit(1)'

Run a targeted CI check for a narrow rule:

npx @sha3/code verify --report json --only single-return

Troubleshooting verify

If verify fails, first decide what kind of failure it is:

• contract/metadata/layout problem: check AGENTS.md, ai/contract.json, package.json.codeStandards, or missing scaffold files
• source-rule problem: use the reported ruleId, file path, and verify --explain <rule-id>
• README problem: restore the required sections

Common cases:

• unknown rule id in --only: use code-standards verify --explain <rule-id> or inspect resources/ai/rule-catalog.json
• too much output: narrow the run with --only or --files
• Biome and TypeScript pass but verify fails: expected, because verify checks product policy and contract rules that generic tooling does not cover, but line-wrapping disputes should now be treated as Biome territory

Required README headings in generated projects

Keep these headings in generated projects, at minimum:

• for both templates: ## TL;DR, ## Why, ## Main Capabilities, ## Installation, ## Usage, ## Examples, ## Public API, ## Configuration, ## Compatibility, ## Scripts, ## Structure, ## Troubleshooting, ## AI Workflow
• for node-service also: ## Running Locally and ## HTTP API

VS Code formatting conflicts

Use the biomejs.biome extension as the default formatter for generated projects.

AI Workflow

Generated projects treat these files as the local AI contract:

1. ai/contract.json
2. AGENTS.md
3. SKILLS.md
4. skills/*
5. ai/rules.md
6. ai/<assistant>.md

Recommended bootstrap prompt:

Before generating code:
- Read AGENTS.md, SKILLS.md, ai/contract.json, ai/rules.md, and ai/<assistant>.md.
- Load `skills/init-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md` for init-based implementation.
- Load `skills/refactor-workflow/SKILL.md`, `skills/feature-shaping/SKILL.md`, `skills/simplicity-audit/SKILL.md`, and `skills/change-synchronization/SKILL.md` for refactor work.
- Load `skills/test-scope-selection/SKILL.md` for meaningful behavior changes, `skills/readme-authoring/SKILL.md` whenever README changes, and `skills/http-api-conventions/SKILL.md` whenever HTTP endpoints exist or change.
- Summarize the `error` rules and the `warning` rules you will review carefully.
- Implement the task without editing managed files unless this is a standards update.
- Run npm run check and fix all failures before finishing.

For a standards migration on an existing repo, run refactor first and then use the generated files under .code-standards/refactor-source/ as reference context for the rewrite.