harness-init

Files (71)

• SKILL.md
• dev-api.md.tmpl · templates/backend/.harness/agents/
• dev-db.md.tmpl · templates/backend/.harness/agents/
• dev-services.md.tmpl · templates/backend/.harness/agents/
• 50-backend.md · templates/backend/.harness/rules/
• verify_all.sh.tmpl · templates/backend/.harness/scripts/
• SKILL.md.tmpl · templates/backend/.harness/skills/build/
• SKILL.md.tmpl · templates/backend/.harness/skills/test/
• SKILL.md.tmpl · templates/backend/.harness/skills/verify/
• settings.json.tmpl · templates/common/.claude/
• copilot-instructions.md.tmpl · templates/common/.github/
• decision-rubric.md · templates/common/.harness/
• insight-index.md.tmpl · templates/common/.harness/
• code-reviewer.md · templates/common/.harness/playbooks/
• developer.md · templates/common/.harness/playbooks/
• gate-reviewer.md · templates/common/.harness/playbooks/
• pm-orchestrator.md · templates/common/.harness/playbooks/
• qa-tester.md · templates/common/.harness/playbooks/
• requirement-analyst.md · templates/common/.harness/playbooks/
• solution-architect.md · templates/common/.harness/playbooks/
• supervisor.md · templates/common/.harness/playbooks/
• rejected-decisions.md · templates/common/.harness/
• 00-core.md.tmpl · templates/common/.harness/rules/
• 05-insight-index.md.tmpl · templates/common/.harness/rules/
• 25-decision-policy.md · templates/common/.harness/rules/
• 60-tool-handoff.md · templates/common/.harness/rules/
• 65-intervention.md.tmpl · templates/common/.harness/rules/
• 70-doc-size.md.tmpl · templates/common/.harness/rules/
• 75-safety-hook.md.tmpl · templates/common/.harness/rules/
• _ai-native-prompt.md · templates/common/.harness/rules/
• ai-native-mock.json · templates/common/.harness/scripts/
• ambient-prompt.sh · templates/common/.harness/scripts/
• ambient-reset.sh · templates/common/.harness/scripts/
• archive-task.sh · templates/common/.harness/scripts/
• doc-query.js · templates/common/.harness/scripts/
• guard-rm.js · templates/common/.harness/scripts/
• guard-rm.sh · templates/common/.harness/scripts/
• harness-sync.sh · templates/common/.harness/scripts/
• hook-spec.js · templates/common/.harness/scripts/
• hook-spec.sh · templates/common/.harness/scripts/
• install-hooks.js · templates/common/.harness/scripts/
• install-hooks.sh · templates/common/.harness/scripts/
• language-policy.sh · templates/common/.harness/scripts/
• memory-seed.js · templates/common/.harness/scripts/
• memory-sink.js · templates/common/.harness/scripts/
• memory.js · templates/common/.harness/scripts/
• migrate-scripts-layout.sh · templates/common/.harness/scripts/
• stage-schema.js · templates/common/.harness/scripts/
• task-state.js · templates/common/.harness/scripts/
• upgrade-project.sh · templates/common/.harness/scripts/
• AI-GUIDE.md.tmpl · templates/common/
• CLAUDE.md.tmpl · templates/common/
• CONTEXT.md · templates/common/
• dev-map.md.tmpl · templates/common/docs/
• README.md · templates/common/docs/spec/
• tasks.md.tmpl · templates/common/docs/
• workflow.md · templates/common/docs/
• golden-tasks.md.tmpl · templates/common/evals/
• dev-backend.md.tmpl · templates/fullstack/.harness/agents/
• dev-db.md.tmpl · templates/fullstack/.harness/agents/
• …and 11 more

SKILL.md (first lines)

# /harness-init

Bootstrap a new project with the complete Harness skeleton, so that Claude Code can run
the 7-agent pipeline (PM → Analyst → Architect → Gate → Developer → Reviewer → QA)
out of the box.

The default model is **plugin-native** (v0.30+):

- The 7 framework agents (PM / Analyst / Architect / Gate / Developer / Reviewer / QA,
  plus the auxiliary supervisor) are **provided by the harness-kit plugin** and dispatched
  as `harness-kit:<name>` — they are **not copied into the project**.
- `.harness/` is the project's source of truth for **rules** and **skills**, plus any
  **project-specific partition `dev-*` agents** (only in partitioned projects).
- `.claude/agents/` and `.claude/skills/` are regenerated from `.harness/agents/` (partition
  `dev-*` only) and `.harness/skills/` via `.harness/scripts/harness-sync`. A single-developer
  project has no `.harness/agents/` to sync — its agents all come from the plugin.
- `CLAUDE.md` and `.github/copilot-instructions.md` are ~15-line static stubs
  written once during init; they point at `AI-GUIDE.md`, which indexes
  `.harness/rules/*.md` by reference (since v0.10 rules are not composed).

## When to invoke

- New empty project repo
- Greenfield directory where you want AI-driven development to start

For **existing** projects with code, use `/harness-adopt` instead.

## Procedure

Follow these steps strictly. Use `TodoWrite` to track them.

### 1. Confirm the target directory

The current working directory is the target. Confirm with the user:

> "I'll initialize Harness in `<cwd>`. Proceed? (yes / change directory)"

If the directory already contains `.harness/`, `.claude/agents/`, or `CLAUDE.md`,
**stop and tell the user** — running this would overwrite existing files. Suggest
they back up or run `/harness-adopt`.

### 2. Gather project info via `AskUserQuestion`

Ask **six questions** in a single `AskUserQuestion` call:

1. **Project type** — options. The choice determines `PROJECT_TYPE` placeholder and which overlay is copied.
   - `Fullstack (frontend + backend + DB)` — `PROJECT_TYPE=fullstack`; copies fullstack overlay (partition agents, fullstack rules, verify_all preset for Node/web stacks).
   - `Backend / API service` — `PROJECT_TYPE=backend`; copies backend overlay (api/services/db partitions, backend rules, multi-stack verify_all).
   - `Generic (CLI / library / mobile / ML / embedded / etc.)` — `PROJECT_TYPE=generic`; copies generic overlay (`50-generic.md` stub for project-specific rules + a generic `verify_all` you customize for your actual build/test commands). No partition agents by default. The AI fills in `50-generic.md` based on your Q2 stack description and any existing code in the target directory.
2. **Primary language / framework stack** — free text via "Other" option (e.g. "Next.js + NestJS + Postgres", "FastAPI + Postgres", "Rust CLI tool", "PyTorch training pipeline").
3. **Install auto-sync hooks?** — options:
   - `Yes (recommended)` — installs **both** the Claude Code Stop hook (in `.claude/settings.json`) **and** the git pre-commit hook (via `.harness/scripts/install-hooks.sh`). Stop hook keeps `CLAUDE.md` + `.github/copilot-instructions.md` fresh while you work in Claude Code. Pre-commit hook is the tool-agnostic backstop — blocks any commit (Claude Code, Copilot, Cursor, hand-edits) that includes drifted generated artifacts.
   - `No, manual only` — you run `.harness/scripts/harness-sync` yourself after `.harness/` edits. `verify_all` will still catch drift after the fact, but you lose the auto-fresh guarantee.
4. **Developer partitioning** — options depend on Q1:

   For **Fullstack**:
   - `Partitioned (recommended) — dev-frontend / dev-backend / dev-db agents` — better focus, cleaner reviews, cross-area tasks via Architect partition assignment
   - `Single developer — one agent for all code` — simpler, fewer agents, fine for small projects

   For **Backend** (v0.5+):
   - `Partitioned (recommended) — dev-api / dev-services / dev-db agents` — three-layer split (HTTP boundary / business logic / persistence), supports clean coordination per Architect's design
   - `Single developer — one agent for all code` — fine for small/flat backend projects without a layered architecture

   For **Generic**:
   - Skip this question. Defaults to single developer. After init, the AI can be asked to "add partition agents for X" — it will create custom `.harness/agents/dev-*.md` based on the actual project layout. See `.harness/rules/50-generic.md` for the documented partitioning procedure.

5. **Project output language** — this is a **project-wide policy**, not just doc language. Options:
   - `English (default)` — **All AI output in this project will be in English**. That includes: chat replies, agent-to-agent hand-offs, every per-task document under `docs/features/<task>/`, updates to `tasks.md` / `dev-map.md`, error messages, status reports. Even if the user writes in another language, AI responds in English.
   - `中文 (Chinese)` — **按消费者分流**：面向人的产出（对话回复、错误消息、状态/进度报告、给用户的交付总结、README 及人读文档）用**中文**；面向下游 agent/LLM 的产出（01–07 阶段文档、PM_LOG、tasks.md/dev-map/insight-index 台账、agent/rule/AI-GUIDE/CLAUDE 编辑、代码注释、commit message）用**英文**。即使用户用其他语言提问，对话回复仍用中文。
   - The policy is enforced by an "Output language" section at the top of CLAUDE.md. Agents read CLAUDE.md and follow the rule.
   - Agent definitions and verify_all scripts stay in English regardless (LLM reads English fine, file count manageable). Only output is constrained.

6. **AI customization of `50-<project>.md` rule fragment (v0.16+)** — opt-in. Default: `No (static template only)`.
   - `No (default) — keep static stub` — copies the static `50-<type>.md` template unchanged (byte-identical to v0.15.1 behavior). Fastest, most predictable init. The user/AI can edit the stub later by hand.
   - `Yes — let AI draft a tailored 50-<project-slug>.md` — after the static templates are copied (step 4) and placeholders are substituted (step 5), the skill runs an inline AI customization step (5b) that: (a) reads the user's Q2 stack string, the target directory's top-level filenames (Glob `*`, capped at 100 entries), and the contents of any of these manifest files if present (`package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `README.md`, each capped at 50 KB); (b) drafts `.harness/rules/50-<project-slug>.md` whose six section headings match the static stub but whose body is grounded in the inputs above (every non-template section carries an inline `<!-- source: ... -->` HTML comment with the file or tag the claim came from); (c) optionally proposes one or more `.harness/agents/dev-<name>.md` partition drafts that the user accepts / renames / rejects individually before any file is written.
   - Tradeoff: ~10s extra in init; AI output is non-deterministic (mitigated by mandatory source citations and a fall-back to the static stub if the four invariants fail — see step 5b.5). The user can always edit the file after init.
   - Reserved-name guard: partition names matching the seven pipeline-agent names (`pm-orchestrator`, `requirement-analyst`, `solution-architect`, `gate-reviewer`, `developer`, `code-reviewer`, `qa-tester`) are silently dropped before the Accept prompt.

### 3. Locate the template directory

Templates live alongside this skill:

- `<skill-root>/templates/common/` — shared assets (rule fragments in `.harness/rules/`,
  stage playbooks in `.harness/playbooks/`, harness-sync scripts, docs, evals). The framework
  agents are **not** here anymore — they are plugin-provided (`harness-kit:<name>`); their
  playbooks are, because an agent Reads its playbook from the PROJECT.
- `<skill-root>/templates/fullstack/` — fullstack-specific overlays.
- `<skill-root>/templates/backend/` — backend-specific overlays.
- `<skill-root>/templates/generic/` — generic project overlay (single `50-generic.md` stub).
- `<skill-root>/templates/i18n/<lang>/` — translation overlays (currently `zh` is provided). Mirror the directory structure of `common/` and `<project-type>/`; files inside override their English counterparts.

If the skill is installed under `~/.claude/skills/harness-init/`, the templates are at `~/.claude/skills/harness-init/templates/`. Use `Glob` to discover the actual path.

### 4. Copy template files

Copy in this order (later layer overwrites earlier):

1. Everything under `templates/common/` → target root.
2. Everything under `templates/<project-type>/` → target root.
   - Fullstack overlay adds `.harness/rules/50-fullstack.md`, `.harness/skills/{build,test,verify}/SKILL.md.tmpl`, `.harness/scripts/verify_all.sh.tmpl`, **and** `.harness/agents/dev-{frontend,backend,db}.md.tmpl` (partition agents).
   - Backend overlay adds `.harness/rules/50-backend.md` etc.
   - **Generic** overlay adds `.harness/rules/50-generic.md` (a near-empty stub the user/AI fills in based on the actual stack). No partition agents. No project-type-specific `verify_all` template — the project gets the generic `verify_all` from `common/` (TODO: ship a `verify_all.tmpl` in `generic/` once the common one has stack-agnostic skeleton).
3. **If Q5 ≠ English**, apply the language overlay:
   - Copy everything under `templates/i18n/<lang>/common/` → target root (overwrites the English files).
   - Copy everything under `templates/i18n/<lang>/<project-type>/` → target root.
   - The `zh` overlay carries only the **human-facing files** a generated zh project should read in Chinese: `docs/spec/README.md` and `evals/golden-tasks.md.tmpl`. The three policy-carrying surfaces (`.harness/rules/00-core.md`, `CLAUDE.md`, `.github/copilot-instructions.md`) are **no longer overlaid** — they are laid down in English by step 4.1 and then have their Chinese consumer-split output-language policy injected by step 4.4 (composition, not duplication; T-016). Per the output-language policy, every AI-facing framework file (`AI-GUIDE.md`, the other rule fragments, the type `50-*.md`, `.harness/insight-index.md`, `docs/workflow.md`, `docs/dev-map.md`, `docs/tasks.md`) is NOT in the zh overlay and therefore falls through to its English `common/`/type version.
   - Files **not** in the overlay (agent prompts, skills/build|test|verify SKILL.md, scripts, **and the AI-facing framework files just listed**) stay in English. This is intentional — it is the mechanism that anglicizes AI-facing scaffolding: LLM reads English fine, the framework internals stay consistent, and the file count stays manageable.

### 4.4 Inject the output-language policy (only if Q5 = 中文)

For a `zh` project, the English `common/` `.harness/rules/00-core.md`, `CLAUDE.md`, and
`.github/copilot-instructions.md` were laid down by step 4.1 and are still English. Convert their
policy region to the canonical Chinese policy by running the **already-distributed** helper against the
project root (it was copied into `.harness/scripts/` by step 4.1):

`<template-root>` is the resolved plugin/skill root discovered in step 3 — the directory that **contains**
`skills/harness-init/templates` (i.e. the same value `/harness-language` passes; NOT the `templates`
directory itself). The helper:
- reads the single-source snippet `skills/harness-init/templates/i18n/zh/_policy/output-language.zh.md.tmpl`

From Alan-IFT/harness-kit, MIT.

More from Alan-IFT/harness-kit