@nextstage-brasil/harness

One CLI to install NextStage agent skills, scaffold Spec-Driven Development (SDD) layout, and keep Cursor / Claude Code rules in sync.

Stop wiring skills by hand. Point harness at your project, pick a preset (or a single skill), and get a ready workspace: skills under .agents/skills/, canonical rules under .nextstage-harness/, generated adapters for your agents, plus a baseline AGENTS.md.

npx @nextstage-brasil/harness

Interactive wizard. Prefer CI / scripts? Use flags below — every common path is copy-paste ready.

Requires: Node.js 18+ · works with Cursor and Claude Code · skills from nextstage-brasil/skills

What you get

| After init | Why it matters | | --------------------------------------------- | ------------------------------------------------------ | | .agents/skills/ | Installed skills (Skills CLI). Cursor reads them here. | | .nextstage-harness/rules/ | Edit rules here — single source of truth | | .cursor/rules/, .claude/rules/ | Generated adapters — do not edit by hand | | AGENTS.md + CLAUDE.md | Project entry for agents | | docs/context, docs/specs, docs/versions | SDD folders (sdd/ + pm/ per version; unless --no-scaffold) |

Every install also pulls alwaysInstall skills: ns-harness (plus its dependencies). Presets add Spec-Driven, PM, GitLab, and other packs on top.

Quick start

# 1. From your project root
cd your-project

# 2. Interactive (recommended first time)
npx @nextstage-brasil/harness

# 3. Or skip prompts — Spec-Driven default pack
npx @nextstage-brasil/harness --preset spec-driven --yes

Then open the project in your agent and:

1. Obey AGENTS.md (already in context)
2. Brownfield: run /ns-harness prepare this repo once
3. Delivery: run /ns-spec-driven

See installed presets/skills anytime:

npx @nextstage-brasil/harness list

Pick your scenario

New project (greenfield)

Scaffold + Spec-Driven skills. Start delivering with /ns-spec-driven.

npx @nextstage-brasil/harness --preset spec-driven --yes

Existing codebase (brownfield)

Install a delivery preset, then onboard so agents understand architecture and living specs.

npx @nextstage-brasil/harness --preset spec-driven --yes
# In your agent:
#   /ns-harness prepare this repo

Need the full prepare prompt in the terminal?

npx @nextstage-brasil/harness prepare

GitLab-heavy team

Issue execution, board sync, CI generator, MCP usage — on top of Spec-Driven.

npx @nextstage-brasil/harness --preset gitlab --yes

Project Manager (no code execution)

Human PM workflow only — ns-project-manager (commercial budget, delivery schedule nested in workflow.md). Per-issue grill-me is catalog skill ns-requirements-enricher (GitLab preset). Does not install SDD or coding skills.

npx @nextstage-brasil/harness --preset project-manager --yes

Standalone Claude export (zip, no harness coupling):

cd packages/harness && npm run export:external
# → dist/external/ns-project-manager.zip
# → dist/external/ns-multi-agent-architect.zip

Frontend reverse prototyping

Playwright capture → single prototype/ tree (create or evolve; git versions history) → design + quality → living appearance specs → optional normative visual MDs. Not full SDD.

npx @nextstage-brasil/harness --preset frontend-prototype --yes

Then in your agent: /ns-proto-creator (or /ns-proto-visual-guide for appearance docs only).

Only one skill (no scaffold)

Install a skill + its catalog depends. Skips .nextstage-harness/, AGENTS.md, and docs/.

npx @nextstage-brasil/harness --skill ns-multi-agent-architect --no-scaffold -y
npx @nextstage-brasil/harness --skill ns-coder --skill ns-reviewer --no-scaffold -y

Already have harness? Add a skill and refresh adapters:

npx @nextstage-brasil/harness --skill ns-gitlab-board-sync --no-scaffold -y
npx @nextstage-brasil/harness sync

Preview before writing files

npx @nextstage-brasil/harness --preset gitlab --dry-run
npx @nextstage-brasil/harness --skill ns-frontend-design --dry-run

Cursor only (or Cursor + Claude)

Default agents: cursor + claude-code. Persist Cursor-only and prune Claude adapters:

npx @nextstage-brasil/harness agents set --agent cursor
npx @nextstage-brasil/harness agents          # show current

Refresh skills after a catalog release

Updates only skills that changed (compares local/source content hash, or GitHub tree SHA from skills-lock.json). Skips up-to-date installs. Does not install new catalog entries. Use --force to refresh everything.

npx @nextstage-brasil/harness update
npx @nextstage-brasil/harness update --dry-run
npx @nextstage-brasil/harness update --force

Code complements (UI, docs, security)

With --preset spec-driven, gitlab, or agents, harness resolves ns-coder depends — you get ns-frontend-design, ns-docs-writer, ns-best-practices, ns-backend-tests, and ns-e2e-tests without extra flags. ns-coder and ns-spec-driven delegate to the design/docs/hygiene skills when relevant.

Minimal install only? Add complements explicitly:

npx @nextstage-brasil/harness --skill ns-frontend-design --skill ns-docs-writer --skill ns-best-practices --no-scaffold -y

Agents stack

SDD + LangGraph labs + LangChain/MCP/eval externals:

npx @nextstage-brasil/harness --preset agents --yes

Init into another directory

npx @nextstage-brasil/harness init \
  --dir ./my-agent-service \
  --preset spec-driven \
  --agent cursor \
  --yes

Day-to-day cheat sheet

| Goal | Command | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Install / re-run wizard | npx @nextstage-brasil/harness | | See catalog & presets | npx @nextstage-brasil/harness list | | After editing rules in .nextstage-harness/ | npx @nextstage-brasil/harness sync | | CI: validate harness + regenerate adapters | npx @nextstage-brasil/harness sync | | Update installed skills (changed only) | npx @nextstage-brasil/harness update | | Regenerate AGENTS.md | npx @nextstage-brasil/harness agents-md --force | | Add a project rule | npx @nextstage-brasil/harness add-rule api-conventions --description "REST conventions" | | Add a project subagent | npx @nextstage-brasil/harness add-subagent investigator-agent --skill ns-investigator --description "Investigation bridge" | | Absorb orphan .cursor/rules/*.mdc | npx @nextstage-brasil/harness sync | | Brownfield instructions | npx @nextstage-brasil/harness prepare | | Show / set agents | npx @nextstage-brasil/harness agents · agents set --agent cursor | | Uninstall harness | npx @nextstage-brasil/harness uninstall --dry-run then --yes |

In the agent, invoke skills via menu or slash: /ns-spec-driven, /ns-coder, /ns-reviewer, …

Consumer guide (scaffolded into projects): .nextstage-harness/README.md
Deep installer reference: docs/README_INSTALLER.md

Presets

Base (always): ns-harness (+ transitive deps).

| Preset | Use when you want… | | -------------------- | ----------------------------------------------------------------------------------------------------- | | spec-driven | SDD face + coder, review, investigator, autonomous, living-spec + code complements via ns-coder | | gitlab | Everything in spec-driven, plus GitLab issues, board sync, CI generator, requirements enricher (alias: spec-driven-gitlab) | | project-manager | Human PM toolkit — ns-project-manager only (no SDD/code workers) | | frontend | UI design, reverse prototype (ns-proto-creator), visual guides (alias: frontend-prototype) | | agents | spec-driven + LangGraph labs + ns-postgres-rag + ns-graphrag + LangChain/MCP/eval externals (aliases: agent-creator, agents-api) | | full | Bundled presets (gitlab + frontend + project-manager + agents); includes ns-postgres-rag + ns-graphrag via agents |

npx @nextstage-brasil/harness --preset <name> --yes

Exact skill lists: npx @nextstage-brasil/harness list.

How selection works

Choose one of:

| Mode | Flag | Behavior | | ---------- | --------------------------- | ----------------------------------------------------- | | Preset | --preset <name> | Bundled add-ons + alwaysInstall + depends | | Skills | --skill <id> (repeatable) | Only those skills + catalog depends + alwaysInstall | | Everything | --all | Full NextStage catalog |

Skill ids match directory names under skills/<skill-id>/ in the skills repo. External ids come from external-skills.json (see harness list).

Commands & flags (reference)

Commands

| Command | Description | | ------------------------------ | ---------------------------------------------------------------------------------- | | harness / harness init | Install skills, scaffold, sync adapters, generate AGENTS.md | | harness list | Presets and skill catalog | | harness prepare | Print brownfield prepare instructions (/ns-harness prepare) | | harness sync | Absorb orphan Cursor rules + regenerate adapters; create CLAUDE.md stub if missing when claude-code is active | | harness sync --check | Local — exit 1 if adapters drift, orphan .mdc, or CLAUDE.md missing while claude-code is active | | harness update | Update changed skills in .agents/skills/ (skip up-to-date; --force = all) | | harness agents-md | Generate AGENTS.md + CLAUDE.md (use --force to overwrite) | | harness add-rule <name> | New rule under .nextstage-harness/rules/ + sync | | harness add-subagent <name> | New subagent under .nextstage-harness/agents/ + sync (--skill required) | | harness prune-retired-skills | Remove renamed skill dirs after replacement | | harness uninstall | Remove skills, adapters, .nextstage-harness/, lock, ignore blocks (docs/ kept) | | harness agents | Show active agents from manifest | | harness agents set | Persist agents, sync, prune unused adapter trees |

Common flags

| Flag | Effect | | ----------------------- | --------------------------------------------------------- | | --dir <path> | Target project root (default: .) | | --preset <name> | Preset selection | | --skill <id> | Skill selection (repeatable) | | --all | Full catalog | | --agent <name> | cursor, claude-code (repeatable; default both) | | --source <path\|repo> | Skills source override | | --copy | Copy skills instead of symlinks | | --global / -g | Global skills install (Skills CLI) | | --no-scaffold | Skills only — skip harness layout / AGENTS.md / docs/ | | --keep-agents-md | With uninstall: keep AGENTS.md / CLAUDE.md | | --yes / -y | Non-interactive | | --dry-run | Print plan, write nothing | | --force | Overwrite (agents-md, add-rule, add-subagent) |

add-rule extras: --description, --globs (comma-separated; scoped rule, not always-apply).

add-subagent extras: --skill <id> (required), --description.

Example:

npx @nextstage-brasil/harness add-subagent investigator-agent \
  --skill ns-investigator \
  --description "Investigation bridge"

Full init example

npx @nextstage-brasil/harness init \
  --dir ./my-agent-service \
  --skill ns-multi-agent-architect \
  --skill langchain-fundamentals \
  --agent cursor \
  --agent claude-code \
  --source nextstage-brasil/skills \
  --copy \
  --no-scaffold \
  --yes

Local / monorepo source (maintainers)

This is the same mechanism as npx @nextstage-brasil/harness after publish: npm pack then npx --package=<tgz> harness. --source points at the clone (published npx uses GitHub nextstage-brasil/skills).

# From this repo
bash scripts/local-npx-smoke.sh spec-driven

Or by hand, in an empty project (not inside this clone):

SKILLS_REPO="$HOME/apps/nextstage/skills"   # this clone
VERSION="$(node -p "require('$SKILLS_REPO/packages/harness/package.json').version")"

cd "$SKILLS_REPO/packages/harness" && npm pack --pack-destination /tmp

mkdir -p /tmp/harness-npx-smoke && cd /tmp/harness-npx-smoke && git init

npx --yes --package="/tmp/nextstage-brasil-harness-${VERSION}.tgz" harness \
  --preset spec-driven --yes --dry-run --source "$SKILLS_REPO"

npx --yes --package="/tmp/nextstage-brasil-harness-${VERSION}.tgz" harness \
  --preset spec-driven --yes --source "$SKILLS_REPO"

Do not put init after flags (--source … init is invalid). init is the default, or must be the first argument.

What init does (order)

1. Detects new vs existing project
2. Resolves depends from templates/catalog.json
3. Runs npx skills add → .agents/skills/
4. Scaffolds .nextstage-harness/, .agents/, docs/ (unless --no-scaffold)
5. harness sync — rule adapters + Claude skill symlinks
6. harness agents-md — baseline AGENTS.md + CLAUDE.md

Development

cd packages/harness
npm install
npm test
npm run export:external   # maintainer: dist/external/*.zip (PM + architect)

Release (CI)

On every push to main, .github/workflows/publish-harness.yml:

1. Runs harness tests
2. Reads conventional commits in that push
3. Publishes every push — semver: version: → major, feat: → minor, else → patch
4. Bumps package.json / lockfile, publishes to npm, tags harness-v{version}

One-time npm trusted publishing

Without this, npm publish fails with ENEEDAUTH.

1. Log in at npmjs.com as a maintainer of @nextstage-brasil/harness
2. Package → Settings → Trusted publishing → GitHub Actions
3. Configure: org nextstage-brasil, repo skills, workflow publish-harness.yml
4. Save, push to main

No NPM_TOKEN — OIDC only. Node 24, npm 11.5.1+, id-token: write. Do not set registry-url on setup-node (breaks OIDC).

Manual recovery

If the version landed on main but not on npm: re-run the failed workflow after fixing trusted publishing, or push again to bump and retry.

License

Apache-2.0