Skip to main content
DOCS

Quickstart

Five minutes from zero to a validated employee.md. For the long version, read the README or the integration guide.

  1. 01

    Install the validator

    Python 3.8+ is required. Until employee-md lands on PyPI, install from source — both the CLI (employee-validate) and the Python SDK (runtime) ship in the same package. 

    git clone https://github.com/NosytLabs/employee-md.git
cd employee-md
pip install -e .

    After publishing the package will install with pip install employee-md — the CI snippet below already uses that form.

  2. 02

    Create your employee.md

    Start from this minimum viable spec — it satisfies every required field.

    spec:
  name: "employee.md"
  version: "1.0.0"
  kind: "agent-employment"

role:
  title: "Senior Engineer"
  level: "senior"

mission:
  purpose: "Ship secure, well-tested code."

lifecycle:
  status: "active"
  3. 03

    Validate it

    From the CLI:

    employee-validate employee.md
employee-validate examples/*.md --format compact
employee-validate employee.md --format json

    Or from Python:

    from tooling import EmployeeValidationOrchestrator

orchestrator = EmployeeValidationOrchestrator()
result = orchestrator.validate_file("employee.md")

if result.is_valid:
    print("OK")
else:
    for err in result.errors:
        print(f"{err.field}: {err.message}")

    Want JSON output for CI? Pass --format json.

  4. 04

    Use it from your agent

    The runtime SDK turns the contract into a ready-to-use system prompt + guardrail checker + budget tracker. See the runtime page for the LangChain / OpenAI / Anthropic wiring. 

    from runtime import Employee

emp = Employee.from_file("employee.md")

# Drop straight into your LLM's system slot
system_prompt = emp.system_prompt()

# Cheap pre-flight check against guardrails.prohibited_actions
if not emp.is_action_allowed("delete production database"):
    raise PermissionError("Blocked by employee.md guardrails")

# Track spend against economy.budget_limit
emp.budget.try_spend(0.05)  # raises BudgetExceeded if over cap
  5. 05

    Wire it into CI

    Drop this into your .github/workflows/employee-validate.yml:

    name: validate employee.md
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install employee-md
      - run: employee-validate employee.md --format compact
  6. 06

    Where to next