Back to Details

ns-harness-prepare

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Harness Prepare

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 init
之后编排完整的棕地项目接入流程。你无需替换worker skill，而是按顺序依次运行它们，每一步都是阻塞式执行。当启动检查通过时，无需预先确认。
状态存储在磁盘文件中，而非聊天记录里。在执行后续每一步前，需重新读取之前的输出内容。

Harness discovery

Harness 发现机制

See 
../ns-harness/references/harness-discovery.md
and 
../ns-harness/references/rules-sync.md
.
OutputPath
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
详见
../ns-harness/references/harness-discovery.md
和
../ns-harness/references/rules-sync.md
。
输出内容路径
技术架构规范
{harness_root}/rules/architecture-rules.md
技术栈/模块映射（Agent密集型）
{product_root}/docs/context/brownfield-map.md
业务反向规格说明（面向人类）
{product_root}/docs/context/system-reverse-spec.md
业务反向索引（面向Agent）
{product_root}/docs/context/system-reverse-spec.agent.md
项目Agent入口文件
{product_root}/AGENTS.md
Claude指针文件
{product_root}/CLAUDE.md

When to use

适用场景

TriggerAction
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 docsRe-run full prepare
User wants one worker onlyDo not use this skill — invoke the worker directly
Greenfield, no application codeStop — explain prepare needs a codebase to scan
触发条件操作
刚完成
harness init
（棕地预设）		运行完整准备流程
用户输入"prepare the project" / 
/ns-harness-prepare
运行完整准备流程
重大重构、新增模块/技术栈，或上下文文档过时重新运行完整准备流程
用户仅需运行单个worker请勿使用本skill——直接调用对应worker
绿地项目、无应用代码停止执行——说明准备流程需要扫描代码库

Prerequisites

前置条件

  1. harness init
    completed (or equivalent: 
    .agents/skills/
    + 
    .nextstage-harness/
    present).
  2. Worker skills installed: 
    ns-harness-architecture-rules
    , 
    ns-harness-bootstrap-brownfield
    , 
    ns-harness-codebase-reverse-spec
    , 
    ns-harness-agents-md
    .
  3. 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
  1. 已完成
    harness init
    （或同等条件：存在
    .agents/skills/
    + 
    .nextstage-harness/
    目录）。
  2. 已安装worker skill：
    ns-harness-architecture-rules
    、
    ns-harness-bootstrap-brownfield
    、
    ns-harness-codebase-reverse-spec
    、
    ns-harness-agents-md
    。
  3. 拥有
    {product_root}
    下应用源码的只读访问权限。
若缺少任一worker skill，请停止执行并告知用户：
bash
npx @nextstage-brasil/harness --preset spec-driven --yes

Boot (mandatory, once per session)

启动流程（必填，每会话一次）

  1. Resolve 
    {product_root}
    and 
    {harness_root}
    per harness discovery.
  2. 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
  3. 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.)
  4. If any check fails: show a short failure table (what failed + how to fix) and stop. Do not ask to confirm a broken scope.
  5. 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.
  1. 根据Harness发现机制解析
    {product_root}
    和
    {harness_root}
    路径。
  2. 应用默认配置（检查通过时无需询问）：
    • Markdown产物的输出语言 = 用户会话语言
    • 反向规格说明文件（
      system-reverse-spec.md
      + 
      .agent.md
      ）= 仅支持英文（覆盖会话语言）
    • 反向规格说明范围 = 整个产品；深度 = 管理层视角
    • 模式 = 根据磁盘上现有产物创建或刷新
  3. 执行启动检查：
    • 已安装所需worker skill（
      ns-harness-architecture-rules
      、
      ns-harness-bootstrap-brownfield
      、
      ns-harness-codebase-reverse-spec
      、
      ns-harness-agents-md
      ）
    • {product_root}
      下存在应用代码（清单、
      src/
      、
      app/
      等）
  4. 若任一检查失败：显示简短的失败表格（失败项 + 修复方法）并停止执行。请勿询问用户是否确认有问题的范围。
  5. 若所有检查通过：显示单行或紧凑的范围摘要（
    {product_root}
    、
    {harness_root}
    、语言、反向规格说明默认配置、创建/刷新模式）并立即进入步骤1——无需等待用户确认（如"Confirma?"）。

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.
  • 启动摘要成功后，在同一轮对话中开始步骤1（无需等待确认）。
  • 按照以下固定顺序执行全部四个worker步骤。
  • 步骤间请勿询问"是否继续下一步？"。
  • 启动检查通过时，请勿询问"Confirma?" / 范围确认。
  • 请勿在父会话中自行执行worker工作流——需在同一会话中遵循每个worker skill的工作流（每一步开始时阅读worker的
    SKILL.md
    ）。
  • 请勿跳过
    ns-harness-codebase-reverse-spec
    ——完整准备流程必须包含此步骤。
  • 步骤1完成后，在步骤2前执行
    npx @nextstage-brasil/harness sync
    （shell命令）。

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
WriteCompress
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.
面向Agent的输出不面向人类。在每次写入Agent产物前，需阅读并应用：
../ns-harness/references/agent-artifact-compress.md
写入文件是否压缩
architecture-rules.md
是
brownfield-map.md
是
system-reverse-spec.agent.md
是
AGENTS.md
是
system-reverse-spec.md
否（面向人类）
CLAUDE.md
否（包含规则启动 + AGENTS.md + 
.claude/agents
）
Worker负责执行压缩；若需压缩的文件内容过于冗长（不符合参考文档中的软指标），准备流程将拒绝继续推进。

Step sequence

步骤序列

Step 1 — Architecture rules

步骤1 — 架构规则

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.
Skill: 
ns-harness-architecture-rules
目标: 创建或刷新
{harness_root}/rules/architecture-rules.md
。
提示锚点:
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).
完全遵循worker skill的工作流。仅读取应用代码。

Step 1b — Sync rule adapters (shell)

步骤1b — 同步规则适配器（shell命令）

Run in the project root:
bash
npx @nextstage-brasil/harness sync
Do not proceed to step 2 until sync succeeds.
在项目根目录执行：
bash
npx @nextstage-brasil/harness sync
同步成功后方可进入步骤2。

Step 2 — Brownfield map

步骤2 — 棕地项目映射

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.
Skill: 
ns-harness-bootstrap-brownfield
目标: 创建或更新
{product_root}/docs/context/brownfield-map.md
。
提示锚点:
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).
遵循worker skill的工作流。仅读取应用代码。

Step 3 — Business reverse spec

步骤3 — 业务反向规格说明

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.
Skill: 
ns-harness-codebase-reverse-spec
目标: 创建或更新
{product_root}/docs/context/system-reverse-spec.md
以及 
system-reverse-spec.agent.md
。
提示锚点:
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.
遵循worker skill的工作流。仅生成与技术无关的输出内容。

Step 4 — AGENTS.md (last)

步骤4 — AGENTS.md（最后一步）

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.
Skill: 
ns-harness-agents-md
目标: 刷新
{product_root}/AGENTS.md
并生成极简版
{product_root}/CLAUDE.md
。
提示锚点:
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.
最后执行此步骤，确保链接指向步骤1-3生成的产物。

Per-step validation

逐步骤验证

Before advancing, confirm the step output file exists and is non-stub:
StepFileMin 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.
推进到下一步前，需确认当前步骤的输出文件已存在且非占位文件：
步骤文件最小有效信号
1
architecture-rules.md
包含技术栈、布局或带有真实路径的约束
2
brownfield-map.md
模块表格已填充；技术栈为链接（而非冗长描述）
3
system-reverse-spec.md
+ 
.agent.md
面向人类的文件包含实体/用例；面向Agent的索引包含实体/规则表格
4
AGENTS.md
包含指向harness规则和
docs/context/
目录的链接
若步骤仅生成占位文件或出现错误，停止执行——报告失败的步骤及缺失内容。请勿继续使用上游空产物。

Stop conditions

停止条件

ConditionAction
No application code under 
{product_root}
Stop — show failure; greenfield has nothing to scan
Worker skill not installedStop — show failure; suggest 
harness --preset spec-driven --yes
or 
harness init
Step output missing or still harness stubStop — fix step before continuing
harness sync
fails		Stop — report error
User stops the run mid-chainStop at current step boundary
条件操作
{product_root}
下无应用代码		停止执行——显示失败信息；绿地项目无可扫描内容
未安装worker skill停止执行——显示失败信息；建议执行
harness --preset spec-driven --yes
或
harness init
步骤输出缺失或仍为harness占位文件停止执行——修复当前步骤后再继续
harness sync
执行失败		停止执行——报告错误
用户在流程中途停止运行在当前步骤边界处停止

Completion summary

完成总结

When all steps succeed, report:
  1. Paths written or refreshed (four outputs + sync).
  2. Suggested git commit message: 
    chore: harness prepare — rules, brownfield map, reverse spec (+ agent index), AGENTS.md
  3. Next SDD step: 
    ns-sdd-clarify-requirements
    when ready to plan version 1.0.
所有步骤成功后，报告以下内容：
  1. 已写入或刷新的文件路径（四个输出文件 + 同步操作）。
  2. 建议的git提交信息：
    chore: harness prepare — rules, brownfield map, reverse spec (+ agent index), AGENTS.md
  3. 下一步SDD步骤：准备好规划1.0版本时执行
    ns-sdd-clarify-requirements
    。

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.
  • 启动检查通过时，请勿询问范围确认——显示摘要后直接执行。
  • 请勿调整步骤顺序（尤其是
    ns-harness-agents-md
    不能早于架构规范和上下文产物生成）。
  • 请勿在架构规则步骤后跳过
    harness sync
    。
  • 请勿在完整准备流程中跳过
    ns-harness-codebase-reverse-spec
    。
  • 请勿跳过面向Agent文件的预保存压缩（
    agent-artifact-compress.md
    ）。
  • 请勿粗暴重写面向人类的反向规格说明文件或
    CLAUDE.md
    。
  • 请勿直接编辑
    .cursor/
    或
    .claude/
    目录——仅使用规范路径。
  • 准备流程中请勿修改应用源码。

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.
/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

集成流程

StageSkill
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
阶段Skill
CLI安装 + 脚手架生成
npx @nextstage-brasil/harness init
前置条件检查
npx @nextstage-brasil/harness prepare
准备完成后的SDD规划
ns-sdd-clarify-requirements
→ 
ns-sdd-requirements-generator