Skip to content

AGENTS.md — instructions for AI assistants working in this repo

This is the canonical guidance for any AI agent (Claude Code or otherwise) working in the Soon ISMS repository. CLAUDE.md points here. Humans: see README.md, MASTERPLAN.md and CONTRIBUTING.md.

This repository is Soon's Information Security Management System (ISMS): the policies, procedures and records for ISO/IEC 27001:2022 certification (the primary goal; a SOC 2 report may follow later, reusing the same controls). It is policy documentation only — never application code or secrets. Claude Code is the primary interface both Olaf and Andrea use to prepare and maintain documents.

What Soon is (ground every document in this)

Soon is a privately-held HRTech company (founded 2019) providing a cloud-based Workforce Management (WFM) SaaS — scheduling, time & attendance, leave management, AI forecasting/auto-scheduling. Reuse these facts; don't invent others:

  • Hosting: AWS, eu-west-1 (Ireland); all customer data resident in the EU.
  • Posture: GDPR data processor; TLS 1.2+; AES-256 at rest; MFA enforced for production; SSO/SAML (Entra ID, Okta, Google Workspace).
  • Team: small, fully remote, no offices, no data centres (physical security inherited from AWS, which is independently certified).
  • Stack to reference (not generic placeholders): AWS, GitHub (source + CI/CD), Stripe (payments), Intercom (support), Sentry + CloudWatch (monitoring), Supabase, PostHog, Netlify.
  • Risk appetite: Moderate. Keep policies practical and lean — small company.

Full detail: docs/04-context/ISMS-04-01-context-and-scope.md.

People

  • Olaf Jacobson — internal, technical; owns the repo, tooling, evidence, approvals.
  • Andrea Cardinali — external consultant (CyberSquad); drafts/adapts policies, audit structure. Also writes here, via Claude Code.
  • Standing meeting: Thursdays 13:00 CEST.

Rules when authoring or editing documents

  1. Always include YAML front-matter per docs/_templates/policy-template.md. Required: doc_id, title, type, status. Keep iso27001_controls accurate (the ID↔control map is in ROADMAP.md).
  2. Replace template placeholders with Soon's real specifics. If a fact is unknown, write TODO(owner): <question> — never invent names, numbers, dates, vendors, or approvals.
  3. Every control claim needs evidence. Fill the evidence: list with where an auditor can verify it. Flag claims you can't substantiate.
  4. Be lean. Short, specific, testable text over long generic prose.
  5. Never set status: approved yourself — only a human owner approves (sets approved_by / approved_date / next_review). Use the /isms:approve flow.
  6. After any document change, run python3 tools/isms.py build (regenerates REGISTER.md + STATUS.md) and python3 tools/isms.py check (must be 0 errors).
  7. Never hand-edit REGISTER.md or STATUS.md — they are generated.
  8. Never put application code, secrets, or customer data in this repo.

Document lifecycle (the status field)

template → draft → in-review → approved → (annual review) → approved …
Only approved documents count toward certification. Valid statuses: template, draft, in-review, approved, superseded, not-applicable.

Commands (in .claude/commands/isms/)

Command Purpose
/isms:status Rebuild register/dashboard, validate, summarise standing
/isms:draft <control/doc> Tailor a template into a Soon-specific draft
/isms:review <doc> Review a document as a skeptical auditor
/isms:new <id> "<title>" Scaffold a new document from the template
/isms:approve <doc> Record human owner sign-off
/isms:gap [iso\|soc2] Prioritised list of missing controls/documents (defaults to ISO)
/isms:evidence <control> Verify a policy against the real app/infra (run in that repo)
/isms:meeting Prep the weekly Thursday session

For ad-hoc work without a command, the same task prompts live in prompts/.

Version control (how changes reach main)

main is the live, authoritative state. Never commit ISMS changes directly to main. When doing document work:

  1. Create a branch named by intent: draft/<topic>, review/<topic>, or fix/<topic>.
  2. Make the change there; keep it scoped to one document / one coherent change.
  3. Commit only when the user asks; then open a PR into main (use gh pr create if available, otherwise tell the user the branch is ready to PR).
  4. CI (tools/isms.py check) gates the PR. A bot refreshes REGISTER.md/STATUS.md on merge — you don't need to commit those generated files on a branch.

See CONTRIBUTING.md → "How updates work" for the full model.

Repo conventions

  • tools/isms.py is the source of truth for register/status — never hand-edit the generated files.
  • source/ holds the original Office files — read-only, don't edit.
  • docs/_reference/ and docs/_templates/ are excluded from the compliance register.
  • Strategy is ISO 27001 first — when prioritising, prefer what unblocks ISO certification: the management-system spine (Statement of Applicability, risk assessment & treatment, asset inventory, internal audit, management review, objectives, roles) plus the Annex A controls. A SOC 2 report may follow later and reuses the same controls and evidence, so keep soc2_criteria mappings where easy.