Harness Prepare

Orchestrate the full brownfield onboarding chain after

harness init

. You do not replace the worker skills — you run them in order, one blocking step at a time. No upfront confirmation gate when boot checks pass.

State lives in files on disk, not chat history. Re-read outputs before each subsequent step.

Harness discovery

See

../ns-harness/references/harness-discovery.md

and

../ns-harness/references/rules-sync.md

Output	Path
Technical constitution	`{harness_root}/rules/architecture-rules.md`
Stack / module map (agent-dense)	`{product_root}/docs/context/brownfield-map.md`
Business reverse spec (human)	`{product_root}/docs/context/system-reverse-spec.md`
Business reverse index (agent)	`{product_root}/docs/context/system-reverse-spec.agent.md`
Project agents entry	`{product_root}/AGENTS.md`
Claude pointer	`{product_root}/CLAUDE.md`

When to use

Trigger	Action
Right after `harness init` (brownfield preset)	Run full prepare
User says "prepare the project" / `/ns-harness-prepare`	Run full prepare
Major refactors, new modules/stack, or stale context docs	Re-run full prepare
User wants one worker only	Do not use this skill — invoke the worker directly
Greenfield, no application code	Stop — explain prepare needs a codebase to scan

Prerequisites

harness init

completed (or equivalent:

.agents/skills/

.nextstage-harness/

present).

Worker skills installed:

ns-harness-architecture-rules

ns-harness-bootstrap-brownfield

ns-harness-codebase-reverse-spec

ns-harness-agents-md

Read-only access to application source under
```
{product_root}
```
.

If a worker skill is missing, stop and tell the user:

bash

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

Boot (mandatory, once per session)

Resolve
```
{product_root}
```
and
```
{harness_root}
```
per harness discovery.
Apply defaults (do not ask when checks pass):
- Output language for markdown artifacts = user conversation language
- Reverse-spec (
```
system-reverse-spec.md
```
  +
```
.agent.md
```
  ) = English only (overrides conversation language)
- Reverse-spec scope = whole product; depth = executive
- Mode = create or refresh from existing artifacts on disk

Run boot checks:

Worker skills present (

ns-harness-architecture-rules

ns-harness-bootstrap-brownfield

ns-harness-codebase-reverse-spec

ns-harness-agents-md

)

Application code under
```
{product_root}
```
(manifests,
```
src/
```
,
```
app/
```
, etc.)

If any check fails: show a short failure table (what failed + how to fix) and stop. Do not ask to confirm a broken scope.
If all checks pass: show a one-line or compact scope summary (
```
{product_root}
```
,
```
{harness_root}
```
, language, reverse-spec defaults, create/refresh) and proceed immediately into Step 1 — do not wait for "Confirma?" / user approval.

Orchestration mandate

After a successful boot summary, start Step 1 in the same turn (no confirmation wait).
Execute all four worker steps in the fixed order below.
Do not ask "continue to next step?" between steps.
Do not ask "Confirma?" / scope approval when boot checks are green.
Do not perform worker workflows yourself in the parent session — follow each worker skill's workflow in the same session (read the worker
```
SKILL.md
```
at the start of each step).
Do not skip
```
ns-harness-codebase-reverse-spec
```
— full prepare includes it.
After step 1, run
```
npx @nextstage-brasil/harness sync
```
(shell) before step 2.

Pre-save compress (mandatory)

Agent-facing outputs are not for humans. Before every

Write

of an agent artifact, read and apply:

../ns-harness/references/agent-artifact-compress.md

Write	Compress
`architecture-rules.md`	Yes
`brownfield-map.md`	Yes
`system-reverse-spec.agent.md`	Yes
`AGENTS.md`	Yes
`system-reverse-spec.md`	No (human body)
`CLAUDE.md`	No (Rules boot + AGENTS.md + `.claude/agents` )

Workers own the pass; prepare rejects advancing if a yes-row file looks essay-bloated vs the soft targets in that reference.

Step sequence

Step 1 — Architecture rules

Skill:

ns-harness-architecture-rules

Goal: Create or refresh

{harness_root}/rules/architecture-rules.md

Prompt anchor:

Scan {product_root} and generate or refresh architecture-rules.md.
Evidence-based only; mark inferred items. Target 80–200 lines.
Telegraphic tables/bullets — agent hot memory, not prose.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md (caveman ultra).

Follow the worker skill workflow completely. Read-only on application code.

Step 1b — Sync rule adapters (shell)

Run in the project root:

bash

npx @nextstage-brasil/harness sync

Do not proceed to step 2 until sync succeeds.

Step 2 — Brownfield map

Skill:

ns-harness-bootstrap-brownfield

Goal: Create or update

{product_root}/docs/context/brownfield-map.md

Prompt anchor:

Bootstrap brownfield analysis for {product_root}.
Agent-dense brownfield-map.md (tables only). Link architecture-rules.md for stack — do not duplicate.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md (caveman ultra).

Follow the worker skill workflow. Read-only on application code.

Step 3 — Business reverse spec

Skill:

ns-harness-codebase-reverse-spec

Goal: Create or update

{product_root}/docs/context/system-reverse-spec.md

and

system-reverse-spec.agent.md

Prompt anchor:

Reverse-engineer {product_root} into a technology-agnostic system description.
Executive depth (default). Save human body to docs/context/system-reverse-spec.md
and agent-dense index to docs/context/system-reverse-spec.agent.md.
Both files MUST be English only (titles, labels, prose, rules) — never mix with conversation language.
Compress only the agent index before Write (agent-artifact-compress.md). Leave human body readable.
Autonomous run: use boot defaults for scope; English for reverse-spec; skip recon checkpoint unless a blocker.

Follow the worker skill workflow. Technology-agnostic output only.

Step 4 — AGENTS.md (last)

Skill:

ns-harness-agents-md

Goal: Refresh

{product_root}/AGENTS.md

and write minimal

{product_root}/CLAUDE.md

Prompt anchor:

Refresh AGENTS.md for {product_root} from installed skills and artifacts produced in this session.
Link to architecture-rules.md, brownfield-map.md, system-reverse-spec.md, and system-reverse-spec.agent.md — do not duplicate their bodies.
Preserve hand-edited sections unless recon proves them wrong.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md — target ~95–110 lines.

Run last so links point to artifacts from steps 1–3.

Per-step validation

Before advancing, confirm the step output file exists and is non-stub:

Step	File	Min signal
1	`architecture-rules.md`	Stack, layout, or constraints with real paths
2	`brownfield-map.md`	Module tables filled; stack is pointer (not a prose dump)
3	`system-reverse-spec.md` + `.agent.md`	Human body has entities/use cases; agent index has entity/rule tables
4	`AGENTS.md`	Links to harness rules and `docs/context/`

If a step produces only a stub or errors, stop — report which step failed and what is missing. Do not continue with empty upstream artifacts.

Stop conditions

Condition	Action
No application code under `{product_root}`	Stop — show failure; greenfield has nothing to scan
Worker skill not installed	Stop — show failure; suggest `harness --preset spec-driven --yes` or `harness init`
Step output missing or still harness stub	Stop — fix step before continuing
`harness sync` fails	Stop — report error
User stops the run mid-chain	Stop at current step boundary

Completion summary

When all steps succeed, report:

Paths written or refreshed (four outputs + sync).

Suggested git commit message:

chore: harness prepare — rules, brownfield map, reverse spec (+ agent index), AGENTS.md

Next SDD step:
```
ns-sdd-clarify-requirements
```
when ready to plan version 1.0.

Forbidden

Do not ask for scope confirmation when boot checks pass — show summary and proceed.
Do not reorder steps (especially
```
ns-harness-agents-md
```
before constitution and context artifacts).
Do not skip
```
harness sync
```
after architecture rules.
Do not skip
```
ns-harness-codebase-reverse-spec
```
in full prepare.
Do not skip pre-save compress on agent-facing files (
```
agent-artifact-compress.md
```
).
Do not caveman-rewrite the human reverse-spec body or
```
CLAUDE.md
```
.
Do not edit
```
.cursor/
```
or
```
.claude/
```
directly — canonical only.
Do not modify application source code during prepare.

Invocation examples

/ns-harness-prepare

I just ran harness init on this brownfield repo. Run full prepare for {product_root}.

Prepare the project — architecture rules, brownfield map, reverse spec, and AGENTS.md in one go.

Integration

Stage	Skill
CLI install + scaffold	`npx @nextstage-brasil/harness init`
Check prerequisites	`npx @nextstage-brasil/harness prepare`
SDD planning after prepare	`ns-sdd-clarify-requirements` → `ns-sdd-requirements-generator`

ns-harness-prepare

NPX Install

Tags

SKILL.md Content

Harness Prepare

Harness discovery

When to use

Prerequisites

Boot (mandatory, once per session)

Orchestration mandate

Pre-save compress (mandatory)

Step sequence

Step 1 — Architecture rules

Step 1b — Sync rule adapters (shell)

Step 2 — Brownfield map

Step 3 — Business reverse spec

Step 4 — AGENTS.md (last)

Per-step validation

Stop conditions

Completion summary

Forbidden

Invocation examples

Integration