Skip to content

Profile fields

Validated against app ae3b0ef2 and Collector 0.9.0 (54621da), 11 November 2026. This page as Markdown

Generated from humanload/vendor/humans-core/spec/schema/humans.schema.json, humanload/vendor/humans-core/spec/schema/instructions.json. This page changes only when that code changes.

A profile is a HUMANS.md file, format version 0.3. Every field is optional except the four the last table marks. Each closed value produces one fixed English sentence: the instruction line an agent receives with the profile. Below, each value is followed by its sentence.

What the first line holds.

  • tldr: Open with a brief summary.
  • decision_needed: Open with the decision you need from the recipient.
  • context: Open with the context needed to understand the message.
  • question: Open with the question you need answered.
  • next_action: Open with the next action the recipient should take.
  • minimal: Keep the complete message to the bare essentials, at most five lines; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.
  • short: Keep the complete message short, at most one screen; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.
  • standard: Give enough detail to understand the main point.
  • thorough: Explain the reasoning and relevant details thoroughly.

Cap on the entire message, including an appendix, tables and code; never bypass via an unsolicited thread or extra message.

A whole number from 20 to 2000.

An agent is told: Keep the complete message, including any appendix, within reading.max_words words; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.

  • bullets: Organize the message as bullet points.
  • prose: Write in connected paragraphs.
  • mixed: Combine short paragraphs with lists where useful.
  • numbered: Number steps and questions so the recipient can answer by number.

Preferred forms, most wanted first.

A list of at most 5 values, without repeats.

  • table: Prefer a table where one fits.
  • diagram: Prefer a diagram where one fits.
  • chart: Prefer a chart where one fits.
  • example: Prefer an example where one fits.
  • text: Prefer plain text.
  • non_technical: Explain the practical meaning in everyday language.
  • balanced: Balance technical detail with a plain-language explanation.
  • expert: Use precise technical detail suited to an expert.
  • avoid: Use familiar words rather than jargon.
  • define: Explain each specialist term once, in a short phrase.
  • ok: Use specialist terms where they make the explanation precise.
  • direct: State the point directly.
  • neutral: Use a neutral tone.
  • warm: Use a warm, considerate tone.
  • numbers_and_sources: Back claims with numbers and their source; leave a placeholder rather than invent a figure.
  • key_numbers: Include the key numbers that support the point.
  • light: Keep supporting evidence brief while staying accurate.

flag_explicitly: say what was checked and what was assumed.

  • flag_explicitly: Say explicitly what you checked and what you assumed.
  • inline: State uncertainty next to the claim it qualifies.

What the last line holds; never invent an action or a question to fill it.

  • next_action: End with one small, concrete action the recipient can take right away, if there is one; it follows deciding.out_of_scope_steps.
  • one_question: End with the single most useful open question, if there is one; it counts toward deciding.asks_per_message.
  • nothing: End when the content ends, with no closing offer, question or next step.

Not a field you can set. It appears only in the merged preferences of a group (get_audience_profile), when its members ask for different values of reading.technical_depth.

  • balanced: In an appendix or details given on request, balance technical detail with plain language, within the same word cap.
  • expert: In an appendix or details given on request, add precise technical detail, within the same word cap.

Only for actions the agent is already allowed to take. Never grants a permission.

  • decide_and_report: For a reversible choice you are already allowed to make, decide and report it; this grants no permission.
  • ask: Ask before settling a reversible choice within the task.
  • end_of_task: Gather non-blocking questions at the end of the task.
  • as_they_come: Raise questions as they arise.
  • always: Give a recommended answer with each question, unless deciding.format is options_only.
  • when_obvious: Give a recommended answer when the choice is clear, unless deciding.format is options_only.
  • one: Limit each message to one question or request.
  • few: Keep each message to a few questions or requests.
  • any: Include as many questions or requests as the message needs.
  • recommendation_first: State your recommendation before the alternatives.
  • options_then_recommendation: Present the options, then your recommendation.
  • options_only: Present the options without a recommendation.

How each question is phrased; yes_confirms_recommendation falls back to multiple_choice without a recommendation.

  • open: Ask open questions that the recipient answers in their own words.
  • multiple_choice: Offer short labelled options so the recipient can answer with a label; with no options to offer, ask openly.
  • yes_confirms_recommendation: Phrase each question so that a plain yes accepts your recommendation; without one, offer short labelled options; with no options to offer, ask openly.
  • welcome_early: Raise disagreements early.
  • after_draft: Present a draft before raising disagreements.
  • on_request: Raise disagreements only when asked.
  • omit_unless_blocking: In closing lines, do not list next steps outside the task, such as merge or deploy, unless one blocks it.
  • list: In closing lines, list relevant next steps outside the task as suggestions, not as permission.
  • blocking_only: Interrupt only when you are blocked.
  • blocking_or_risky: Interrupt when you are blocked or a significant risk needs attention.
  • anything: Interrupt whenever an update is relevant.
  • project: Group updates by project.
  • none: Present updates without grouping them by project.

Stored but inactive; omitted from projections and group merges.

Values: summary_later, urgent_only, as_usual. No instruction sentence: the value is stored and not served.

  • async_written: For a complex topic, suggest a written, asynchronous exchange.
  • sync_call: For a complex topic, suggest a live conversation.
  • either: For a complex topic, written and live exchanges are equally suitable.

How a long task reports where it stands in its own conversation; never a reason to message elsewhere.

  • every_message: During a long task, state in each message where the work stands, such as step 3 of 5.
  • phase_changes: During a long task, state where the work stands only when a phase starts or ends.
  • end_only: During a long task, report progress once, at the end.

When agents do not interrupt the owner, in the owner’s time zone. Times only, never a reason. from and to must differ (SPEC § 3.5). Omitted from groups and stored variants.

  • time_zone: one of the 419 time zone names of the format.
  • from: matches ^(?:[01][0-9]|2[0-3]):(?:00|30)$. Start of the daily quiet range, HH:MM on the hour or half hour, inclusive.
  • to: matches ^(?:[01][0-9]|2[0-3]):(?:00|30)$. End of the daily quiet range, exclusive; earlier than from means the range crosses midnight.
  • all_day: a list of at most 7 values out of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Weekdays that are quiet all day. An empty list means none, like every optional list (SPEC § 3.2); projections omit it.

An agent is told: Do not interrupt during interrupting.quiet_hours, read in its time zone; hold what can wait until they end, or say so to the person you work for.

  • walls_of_text: Break up dense passages.
  • filler_intro: Start with useful information, without a filler introduction.
  • filler_outro: End after the useful information, without a filler conclusion.
  • hedging: Use precise wording without needless hedging, while keeping real uncertainty.
  • emoji: Leave emoji out.
  • rhetorical_questions: State the point without rhetorical questions.
  • multiple_asks: Keep the message to one ask.
  • unexplained_acronyms: Expand acronyms at first use.
  • passive_voice: Use the active voice.
  • exclamation: Use periods rather than exclamation marks.
  • long_preamble: Keep any preamble brief.
  • nested_bullets: Use flat lists without nested bullets.
  • sarcasm: Use literal language without sarcasm.
  • recap: Do not restate at the end what the message or the work already showed.
  • idioms: Use literal words rather than idioms or stock phrases.

A list of at most 10 language codes, the first one first, out of the 183 two-letter codes of the format (aa to zu).

An agent is told: Write to the recipient in the first language listed in languages, even when they write in another; task content such as documents, code or site copy keeps the language its task or repository sets.

Served as data, without an instruction sentence. The server’s instructions tell an agent to hold a request whose kind is not in context.decides.

One value.

software-engineer, senior-engineer, staff-engineer, principal-engineer, tech-lead, architect, engineering-manager, director-of-engineering, vp-engineering, cto, sre, devops-engineer, security-engineer, qa-engineer, data-engineer, data-scientist, ml-engineer, product-manager, product-owner, designer, ux-researcher, technical-writer, founder, ceo, coo, cfo, operations, marketing, sales, customer-support, legal, finance, people-ops, researcher, student

A list of at most 15 values.

javascript, typescript, python, php, ruby, go, rust, java, kotlin, swift, c-cpp, csharp-dotnet, elixir, scala, sql, shell, react, vue, svelte, angular, node, symfony, laravel, rails, django, spring, frontend, backend, mobile, apis, distributed-systems, databases, postgres, mysql, mongodb, redis, search, caching, messaging, data-pipelines, analytics, machine-learning, llm-agents, infrastructure, kubernetes, docker, terraform, ci-cd, observability, incident-response, performance, security, identity-auth, networking, cloud-aws, cloud-gcp, cloud-azure, cloudflare, cloud-costs, testing, accessibility, design-systems, ux-research, product-strategy, roadmap, pricing, billing-payments, growth, seo, marketing, sales, customer-support, compliance, privacy-gdpr, legal, finance, hiring, people-management, project-management, documentation, open-source

A list of at most 15 values, from the same list as context.knows_well.

A list of at most 10 values.

architecture, schema-changes, api-contracts, dependencies, infra-budget, vendor-choice, security-exceptions, data-access, release-scope, release-timing, roadmap-priority, pricing, design, copy-and-content, hiring, team-organization, incident-escalation, legal-review, spending

Values: org, anyone_with_file, private.

The format’s own description of this field:

private: owner only. org: authenticated members of the owner’s organization. anyone_with_file: any reader who has the file; the consumer checks nothing, so where the file is stored controls access. Omission means org for draft compatibility. New-profile compilers should propose explicit private; preserve existing scope unless the owner approves a change. Enforced from trusted context. A reader maps public in a “0.2” profile to anyone_with_file; in “0.3”, public is unknown and makes the profile absent.

On this service, a profile whose visibility is org or anyone_with_file is read by the members of your Teams, and by nobody else. How to ask me explains each value.

Field Required What the format says
humans yes The format version: 0.3.
id yes Unique within its directory. Equals the basename without .md in every directory, except a file named exactly HUMANS.md or an explicitly reported draft validation mode.
name yes Used for resolution only, never served.
updated yes Gregorian calendar date string, years 0000–9999; quoting recommended. No year-0–99 remapping.
aliases no Used for resolution only, never served.
identities no Claims, never proof: resolution goes through the organization directory (SPEC § 7).
states no Stored variants only. Inactive in this draft; no caller state selection and no projection or application of overrides (SPEC § 3.7).
notes no Free text of at most 280 characters. This service stores it and serves it to no agent.