# kith spec v0.1

`kith` is a local, file-based format and protocol for making a person's network
available to planning tools. The source of truth is a directory of Markdown
files. Tools may read those files to suggest who could help with a project, but
they must not contact anyone or mutate the network unless the user explicitly
asks for that in another workflow.

This document is the stable contract for the current proof of concept. The
human guide lives in [`docs/DATA_MODEL.md`](docs/DATA_MODEL.md), and the machine
schema for one person record lives in
[`schema/person.schema.json`](schema/person.schema.json).

## Version

Spec version: `0.1`.

Compatibility rule for v0.x: readers should ignore unknown frontmatter fields
and preserve files they do not understand. Required fields may only change in a
new spec version.

## Directory layout

```text
people/
  _TEMPLATE.md
  first-person.md
  another-person.md
  private/
```

- Person records live in `people/*.md`.
- Files whose names start with `_` are templates or examples and must be ignored
  by readers.
- `people/private/` is optional. Users may gitignore it for sensitive local-only
  records.

## Person record

Each person is one Markdown file named after its `id`:

```text
people/<id>.md
```

The file has YAML frontmatter followed by free-form Markdown notes:

```yaml
---
id: dana-dev
name: Dana
roles: [developer, devops]
skills:
  - TypeScript (expert)
  - Kubernetes (advanced)
can_help_with:
  - Backend architecture reviews
contact: { via: "Signal" }
---
Met at a hackathon. Prefers async.
```

Required fields:

| Field | Type | Requirement |
| ----- | ---- | ----------- |
| `id` | string | Kebab-case, unique, and equal to the filename without `.md`. |
| `name` | string | Display name. |
| `roles` | string array | One or more roles or hats. |
| `skills` | string array | One or more skills. Optional levels may use `Skill (level)`. |

Recommended optional fields:

| Field | Type | Meaning |
| ----- | ---- | ------- |
| `trust` | `high`, `medium`, or `low` | How readily the user would rely on them. |
| `relationship` | string | How the user knows them. |
| `location` | string | Free text location. |
| `availability` | string | Rough availability. |
| `compensation` | `favor`, `paid`, `either`, or `unknown` | Likely engagement style. |
| `domains` | string array | Problem areas. |
| `tools` | string array | Tools, stacks, or platforms. |
| `languages` | string array | Spoken languages. |
| `can_help_with` | string array | Plain-English reasons to approach them. |
| `contact` | object of string values | Channel hints or contact details. |
| `last_contact` | `YYYY-MM-DD` string | Last known contact date. |
| `tags` | string array | User-defined labels. |

Readers must tolerate additional fields.

## Parser subset

The zero-dependency reference CLI supports this YAML subset:

- Scalars: `key: value`
- Inline arrays: `roles: [developer, devops]`
- Block arrays:
  ```yaml
  skills:
    - TypeScript (expert)
    - Kubernetes
  ```
- Inline maps: `contact: { via: "Signal", email: "dana@example.com" }`
- Blank lines and comments beginning with `#` outside quoted strings.

Nested block maps and lists of maps are outside the v0.1 parser subset.

## People plan protocol

When a tool uses `kith` to help produce a project plan, it should append a
section named `People plan`.

The section should include:

- Suggested people to approach.
- Why each person matched.
- Which project needs they cover.
- A contact channel hint only when the tool's privacy contract permits it.
- A `No match for:` line listing uncovered needs.
- The reminder that suggestions are advisory and the user decides who to
  contact.

Example:

```text
People plan:
- Dana (dana-dev) -> Backend architecture reviews; Kubernetes (advanced)
  covers: deploy, kubernetes; trust:high; reach: via: Signal

No match for: payments - do it yourself or bring in someone new.

(Suggestions only - the user decides who to actually contact.)
```

## Privacy contract

`kith` is suggest-only.

- Readers must not contact people.
- Readers must not send messages, calendar invites, emails, or external
  notifications.
- `list_people` and `find_people` style operations should not expose contact
  details.
- `staff_project` style operations may expose one contact channel hint per
  suggested person.
- `get_person` style operations may expose the full contact block because the
  user requested one explicit person.
- Users may keep sensitive records in `people/private/` and gitignore that path.

## Reference commands

```bash
kith init [--private]
kith import csv <file> [--commit] [--private] [--out <dir>]
kith import vcard <file> [--commit] [--private] [--out <dir>]
kith import linkedin <file> [--commit] [--private] [--out <dir>]
kith list
kith find <need>
kith staff <project description>
kith validate
```

The MCP reference server exposes equivalent read-only tools:

- `list_people`
- `find_people`
- `get_person`
- `staff_project`