nfx-guidelines — Nickelfox engineering standards

A small CLI that drops Nickelfox's stack-aware engineering guidelines into a project and wires them into Claude Code, Cursor, and GitHub Copilot so the LLM picks them up automatically.

Supported stacks today:

| id | label | files | |---------------|----------------------|-------| | react | React (SPA, Vite) | best-practices, project-blueprint, bootstrap-prompts, feature-development-workflow | | nextjs | Next.js | best-practices, project-blueprint, bootstrap-prompts | | nodejs | Node.js (backend) | best-practices, project-blueprint, bootstrap-prompts | | python | Python (backend) | best-practices, project-blueprint, bootstrap-prompts | | react-native| React Native (Expo) | best-practices, project-blueprint, bootstrap-prompts | | php | PHP (Laravel-first) | best-practices, project-blueprint, bootstrap-prompts |

Plus a stack-agnostic _core/:

• _core/best-practices.md — universal binding rules (plan-first, doc-first, verify-before-done, etc.).

• _core/feature-development-workflow.md — the universal Discovery → Plan → Document → Contract → Build → Verify → Ship workflow.

• npm package: nfx-guidelines

• Binary: nfx-guidelines

• Repo: Nickelfox/project-engineering

Quick start

New project — pick a stack

cd my-new-app
npx @nickelfox-technologies/nfx-guidelines init --stack nextjs

This will:

1. Create blueprint/_core/ with the universal files.
2. Create blueprint/stacks/nextjs/ with the stack-specific files.
3. Create or update CLAUDE.md, .cursorrules, and .github/copilot-instructions.md with a managed block telling the LLM to read both the _core/ and the active stack's rules.

Then open the project in Claude Code (or Cursor / Copilot) and paste Stage 0 from blueprint/stacks/nextjs/bootstrap-prompts.md to build the project profile.

Monorepo — multiple stacks at once

npx @nickelfox-technologies/nfx-guidelines init --stack nextjs,nodejs

The LLM is told both stacks are active and to apply rules from both under their respective folders.

Existing project — same command, different intent

cd my-existing-app
npx @nickelfox-technologies/nfx-guidelines sync --stack react

Safe to run on any repo:

• blueprint/ files that already exist → skipped (won't clobber a customised version).
• CLAUDE.md / .cursorrules / copilot-instructions.md → only the <!-- nf-guidelines:start -->...<!-- nf-guidelines:end --> block is touched. Anything above/below is yours.

No --stack? The CLI auto-detects + asks

In a TTY, running nfx-guidelines init (no flag) inspects package.json, composer.json, pyproject.toml, etc., suggests likely stacks, and prompts you to confirm. Pass --yes to disable the prompt — useful in CI.

List the stacks

npx @nickelfox-technologies/nfx-guidelines list-stacks

Shorter command (after one-time install)

npm i -g @nickelfox-technologies/nfx-guidelines
nfx-guidelines init --stack nextjs
nfx-guidelines sync
nfx-guidelines list-stacks

Commands

| Command | What it does | | --- | --- | | nfx-guidelines init [target] --stack <ids> | Drop the blueprint into a new project. | | nfx-guidelines sync [target] --stack <ids> | Refresh the blueprint in an existing project. | | nfx-guidelines check [target] | Run pre-PR gates (vulns, outdated, secrets, tests). Exits non-zero on failure. | | nfx-guidelines install-hooks [target] | Install pre-push hook that runs check. | | nfx-guidelines list-stacks | Show all available stacks. | | nfx-guidelines help | Show usage. | | nfx-guidelines version | Show CLI version. |

Options

| Flag | Meaning | | --- | --- | | -t, --target <dir> | Target directory (default: cwd) | | -s, --stack <ids> | Comma-separated stack ids (e.g. nextjs,nodejs) | | -i, --integrations <list> | Subset of claude,cursor,copilot (default: all three) | | -f, --force | Overwrite blueprint files that already exist | | -y, --yes | Non-interactive: fail rather than prompt for stack | | --dry-run | Print what would change without writing | | --skip <gates> | For check: comma-separated gates to skip (vulns,outdated,secrets,tests) | | --only <gates> | For check: only run these gates | | --strict | For check: also fail on outdated packages |

Pre-PR gates (the check command)

nfx-guidelines check runs four gates and exits non-zero if any fail. It's the gatekeeper that makes "no PR with vulns / exposed secrets / failing tests" mechanical instead of a hope.

| Gate | Tooling | Blocks on | |---|---|---| | Vulnerabilities | npm audit --audit-level=high | any high / critical CVE | | Outdated packages | npm outdated | warn-only by default; pass --strict to fail | | Exposed secrets | gitleaks (if installed) → built-in regex fallback | AWS, GitHub, Stripe, OpenAI, JWT, private keys, tracked .env, hardcoded passwords | | Test suite | npm test | any failing test |

Wire it into your workflow

# 1. One-time per repo — install a pre-push hook that runs check
nfx-guidelines install-hooks

# 2. From now on, `git push` runs the gates first
git push
# → blocks if any gate fails. Use `git push --no-verify` only in a documented emergency.

# 3. Same gates in CI via the bundled GitHub Actions template
cp blueprint/_core/ci/pre-pr-checks.yml .github/workflows/
# Mark it as a required status check in branch protection.

For stronger secret detection, install gitleaks once per machine (brew install gitleaks); the CLI prefers it when available.

Full documentation of every gate (what it catches, how to fix failures, what it does NOT cover) lives in blueprint/_core/pre-pr-checklist.md after you run init.

How LLMs pick up the guidelines

| Tool | File the CLI writes to | How the tool reads it | | --- | --- | --- | | Claude Code | CLAUDE.md | Loaded automatically at session start. | | Cursor | .cursorrules | Applied to every Cursor chat / agent run. | | GitHub Copilot | .github/copilot-instructions.md | Loaded by Copilot Chat when present. |

The managed block tells the LLM to:

1. Read blueprint/_core/best-practices.md + _core/feature-development-workflow.md.
2. Read blueprint/stacks/<active>/... for each active stack.
3. Apply universal rules + stack-specific rules.

How safe-merge works

The CLI only ever touches the region between these markers:

<!-- nf-guidelines:start -->
…managed content…
<!-- nf-guidelines:end -->

Everything outside the block is yours. If the markers are missing, the CLI appends a new block at the bottom of the file.

For blueprint/* files the CLI skips any file that already exists. To pull in upstream updates, run nfx-guidelines sync --force (and review the diff).

Adding a new stack

1. Create blueprint/stacks/<id>/best-practices.md, project-blueprint.md, bootstrap-prompts.md.
2. Add an entry to blueprint/stacks/STACKS.json — id, label, description, file list, optional detect rules.
3. Bump the version and re-publish.

Detection rules are best-effort hints; the user can always override with --stack.

Updating to a newer release

nfx-guidelines sync                  # update managed block only
nfx-guidelines sync --force          # also refresh blueprint/*.md

Or with npx (no install needed):

npx @nickelfox-technologies/nfx-guidelines@latest sync

Development

# Run the local checkout against a sandbox
node bin/cli.js init /tmp/sandbox --stack nextjs --dry-run

Zero-dependency, runs on Node ≥ 18.3.

Repo layout

.
├── bin/
│   └── cli.js                       # entry — registered as `nfx-guidelines`
├── blueprint/
│   ├── _core/                       # stack-agnostic universal rules
│   │   ├── best-practices.md
│   │   └── feature-development-workflow.md
│   └── stacks/
│       ├── STACKS.json              # registry (read by CLI)
│       ├── react/
│       ├── nextjs/
│       ├── nodejs/
│       ├── python/
│       ├── react-native/
│       └── php/
├── src/
│   ├── commands/
│   │   ├── apply.js                 # orchestrates init / sync
│   │   └── list.js                  # list-stacks command
│   ├── integrations/
│   │   ├── claude.js
│   │   ├── cursor.js
│   │   └── copilot.js
│   └── lib/
│       ├── blueprint.js             # copies _core + selected stacks
│       ├── fs.js                    # filesystem helpers
│       ├── help.js                  # --help / --version
│       ├── instruction-body.js      # dynamic body referencing active stacks
│       ├── managed-block.js         # idempotent block upsert
│       ├── prompt.js                # interactive stack picker
│       └── stacks.js                # registry loader + auto-detect
├── package.json
└── README.md