Skip to content

docs(readme): lead with npx as the install-free entry point #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
protonspy merged 1 commit into from
Jul 30, 2026
Merged

docs(readme): lead with npx as the install-free entry point #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,18 @@ workflow into a mechanically validated contract for humans and AI agents.

## Use it

No install — run it straight from npm inside the repo you want to govern:

```bash
scc init # scaffold .claude/rules/, the review agents, the layout
scc spec new user-auth # specs/user-auth/: requirements.md, design.md, tasks.md
scc plan new checkout-revamp # plans/checkout-revamp.md
scc validate # every check; exit 2 means it found something
npx @protonspy/scc init # scaffold .claude/rules/, the review agents, the layout
Comment on lines +14 to +17

@coderabbitai coderabbitai Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- README excerpts ---'
cat -n README.md | sed -n '1,70p'
printf '%s\n' '--- package metadata and npx-related references ---'
rg -n -i 'npx|npm install|global|optionalDependencies|bin|protonspy/scc' package.json package-lock.json README.md 2>/dev/null || true

Repository: protonspy/spec-claude-code

Length of output: 5110

🏁 Script executed:

#!/bin/bash
cat -n README.md | sed -n '1,70p'
rg -n -i 'npx|npm install|global|optionalDependencies|bin|protonspy/scc' package.json package-lock.json README.md 2>/dev/null || true

Repository: protonspy/spec-claude-code

Length of output: 5034

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- repository package-related files ---'
git ls-files | rg '(^|/)(package\.json|npm|README\.md)$|package'
printf '%s\n' '--- package manifests ---'
find . -name package.json -not -path './node_modules/*' -print

Repository: protonspy/spec-claude-code

Length of output: 348

🌐 Web query:

npm npx documentation local dependencies prompt --yes cache install latest behavior

💡 Result:

In modern npm (v7.0.0 and later), the npx command functions as a wrapper around npm exec [1][2]. Its behavior regarding local dependencies, cache, and user prompts is summarized below: Local Dependencies and Installation npx first attempts to use binaries available in the local project's node_modules/.bin [1][3]. If a requested package is not present in the local dependencies, npx will install the package to the npm cache and add it to the PATH of the executed process [1][4]. Matching Logic - When a package is specified without a version or specifier, npx matches it with the version existing in the local project if available [1][5]. - If a specific version or specifier is provided, npx only considers it a match if it perfectly matches the local dependency [1][3]. - If no match is found, or if you explicitly request a package via --package, npx installs the required package from the registry [1][3]. Prompting and --yes To prevent accidental execution of incorrect or malicious packages (e.g., due to typos), npx will prompt for confirmation before installing any package that is not already present [1][6]. - You can suppress this interactive prompt by using the --yes (or -y) flag [1][2]. - Providing --yes effectively tells npx to proceed with the installation automatically [1][3]. Caching Packages that are not found locally and require installation are fetched and stored in the npm cache, which is then made available to the executed process [1][4]. Note on Modern vs. Legacy Behavior The standalone npx package was deprecated in npm v7.0.0 [1][2]. Modern npx uses npm exec, which replaced the previous, separate installation logic [1][4]. Older flags like --no-install are deprecated and converted to --no, and --ignore-existing has been removed, as local bins are now always included in the PATH [1][2][4].

Citations:

🏁 Script executed:

#!/bin/bash
git ls-files | rg '(^|/)(package\.json|npm|README\.md)$|package'
find . -name package.json -not -path './node_modules/*' -print

Repository: protonspy/spec-claude-code

Length of output: 281

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- npm/scc/package.json ---'
cat -n npm/scc/package.json
printf '%s\n' '--- npm documentation ---'
cat -n npm/README.md | sed -n '1,180p'
cat -n npm/scc/README.md | sed -n '1,140p'

Repository: protonspy/spec-claude-code

Length of output: 4428

🏁 Script executed:

#!/bin/bash
cat -n npm/scc/package.json
cat -n npm/README.md | sed -n '1,180p'
cat -n npm/scc/README.md | sed -n '1,140p'

Repository: protonspy/spec-claude-code

Length of output: 4373

Make the npx examples accurate and CI-safe.

npx can resolve a matching local dependency or fetch the package into npm’s cache, so “No install” and “always the latest” are misleading. Use “No global install is required,” remove the “always the latest” claim, and add --yes to the pinned CI command.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 14 - 17, Update the README’s npx usage wording to say
that no global install is required, remove any claim that it always runs the
latest version, and add the --yes flag to the pinned CI command while preserving
the existing examples.

npx @protonspy/scc spec new user-auth # specs/user-auth/: requirements.md, design.md, tasks.md
npx @protonspy/scc plan new checkout-revamp # plans/checkout-revamp.md
npx @protonspy/scc validate # every check; exit 2 means it found something
```

Installed globally (`npm i -g @protonspy/scc`) the same commands are just `scc init`,
`scc spec new user-auth`, and so on.

| Command | What it does |
|---|---|
| `init` | Scaffolds the workspace and records what it wrote. Idempotent; never overwrites your edits. |
Expand All @@ -38,8 +43,13 @@ accountability, and a checker that was confidently incomplete would be worse tha

## Install

Published on npm as [`@protonspy/scc`](https://www.npmjs.com/package/@protonspy/scc) —
the launcher pulls the right prebuilt binary for your platform as an optional dependency,
so there is no toolchain to set up.

```bash
npx @protonspy/scc help # no install
npx @protonspy/scc help # no install; pins nothing, always the latest
npx @protonspy/scc@0.0.1 help # pin a version (CI)
npm i -g @protonspy/scc # then: scc help
```

Expand Down
Loading