h-onboard

# h-onboard — First-impression FPF setup (agent-drafts, operator-reviews)

You are onboarding a project to haft. **The agent does the work; the operator reviews.** Spec files are descriptive observation, not binding decisions — Transformer Mandate does NOT prohibit you from authoring them. Your job is to read the repository, infer the project's structure, and produce initial spec drafts. The operator's job is to correct what you got wrong.

## Step 1 — Check current state

Run `mcp__haft__haft_query(action="status")` to confirm `.haft/` exists but has no active SpecSections.

- `ready` → already onboarded; offer `/h-status` instead and stop.
- `needs_init` → operator must run `haft init` from the CLI first (it installs MCP config + skills, this skill cannot do that). Stop and tell them.
- `needs_onboard` → continue.

## Step 2 — Discover the project (agent reads repo)

Read these in parallel before asking the operator anything:

- `README.md`, `README.rst` if present
- Project-config files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, etc.
- Top-level: `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`
- Source entry points: `src/`, `cmd/`, `lib/`, or whatever the project layout uses
- Existing docs: `docs/`, `ADR/`, `decisions/`
- Test layout: `tests/`, `__tests__/`, `*_test.go`, etc.
- CI: `.github/workflows/`, `.gitlab-ci.yml`, `Taskfile.yaml`, `Makefile`

From this you should be able to answer most of these on your own:

- **What is the project?** (library / CLI / service / infra / docs site / something else)
- **Primary tech stack** (language, key frameworks)
- **Who uses it** (other developers / end-users / internal team) — from README
- **How it's released** (PyPI / npm / Docker / binary / git-only) — from config + CI
- **What use cases it serves** — from README intro + examples
- **Load-bearing project-specific terms** — recurring nouns in README and docs that aren't generic engineering vocab

If after this pass you have ambiguity that genuinely blocks drafting (e.g., README is just a logo, or the project does multiple unrelated things), prepare 1-3 short clarifying questions for Step 4. Otherwise skip clarifications and go straight to drafting.

## Step 3 — Draft the three spec files

Write directly to disk using the `Write` tool. Each file starts with a `<!-- DRAFT — onboarding by haft agent on YYYY-MM-DD; operator must review and edit -->` HTML comment so the operator sees it's a starting point, not authoritative.

### `.haft/specs/target-system.md`

The system that delivers value to its users. One section per identifiable use case. Template:

```markdown
<!-- DRAFT — onboarding by haft agent on 2026-XX-XX; operator must review and edit -->

# Target System: <project name>

## Use case: <name from README/docs>

**Who:** <user role, inferred>
**What they do:** <action / outcome, inferred from README>
**Why it matters:** <value statement, inferred>
**Acceptance signal:** <how you can tell it's working — observable, from tests or examples>

## Use case: <next one>
...
```

Aim for 1-4 use cases. If only one is clear, write only one — the operator can add more later. Don't invent use cases that aren't visible in the codebase.

### `.haft/specs/enabling-system.md`

The system that creates and maintains the target system — i.e., the team + their tooling + their process. Inferable from CI files, contributors, code conventions. Template:

```markdown
<!-- DRAFT — onboarding by haft agent on 2026-XX-XX; operator must review and edit -->

# Enabling System

## Team
<inferred from git log authors count, README "Team" / "Contributors" / "Maintainers" section>

## Tooling
- Build: <e.g., `task install` from Taskfile.yaml, `go build`, `npm run build`>
- Test: <e.g., `pytest`, `go test ./...`, `npm test`>
- Lint: <e.g., `ruff`, `golangci-lint`, `eslint`>
- Release: <e.g., GitHub release + PyPI publish, manual, `goreleaser`>

## Process
- CI: <inferred from `.github/workflows/`>
- Branching: <inferred from default branch and any contributing docs>
- Review: <if CODEOWNERS / branch protection inferable>
```

### `.haft/specs/term-map.md`

Project-specific load-bearing terms — vocabulary an outsider would misread. Template:

```markdown
<!-- DRAFT — onboarding by haft agent on 2026-XX-XX; operator must review and edit -->

# Term Map

## <Term 1>
<concise definition, in the project's actual meaning>

## <Term 2>
...
```

Extract these from README headings, docstrings, identifier patterns. Aim for 3-8 entries. Skip generic engineering terms (function, class, test, etc.) — focus on what's *project-specific*.

## Step 4 — Ask only what you couldn't infer

After Step 3, surface to the operator:

```
I drafted three spec files based on reading the repo:
  - .haft/specs/target-system.md
  - .haft/specs/enabling-system.md
  - .haft/specs/term-map.md

I marked them DRAFT. Review and edit where I got things wrong.

[N clarifying questions only if needed]
1. [question 1]
2. [question 2]
```

Clarifying questions are **only** for things you couldn't infer with reasonable confidence. Typical examples:

- "I couldn't determine primary use case — is this a library for application developers, or an end-user CLI?"
- "Observability/monitoring isn't visible in CI — is it in-scope or out-of-scope?"
- "I see two distinct subprojects; should they be one target system or two?"

**Do NOT ask:**

- "What's your target system?" — if you could infer it, just write it.
- "What's the team?" — git log + README give you this.
- "What's in scope?" — out-of-scope is harder, but in-scope is usually obvious.
- "What's your agent autonomy default?" — that's a commission-time decision, not onboarding.

## Step 5 — Frame an onboarding ProblemCard

After drafts are written, record a bootstrap ProblemCard:

```
mcp__haft__haft_problem(
  action="frame",
  problem_type="synthesis",
  title="Project onboarding: <repo name>",
  signal="Project lacks active FPF spec carriers; agent has drafted initial