Skip to content

How we work in this repo

This guide is for everyone writing in the ISMS — Olaf, Andrea (CyberSquad, external), and Melvin. It is deliberately simple. You do not need to be a git expert. The whole point is low friction.

The main way we work is Claude Code. Open this repo in Claude Code and use the /isms:* commands (see README.md §2) — /isms:draft, /isms:review, /isms:new, /isms:status, /isms:approve, etc. They handle the file work, front-matter and validation for you. The git/browser steps below are a fallback for when you'd rather edit by hand.

How updates work (branches → PR → main)

main is the single source of truth — it is the live, current version of every document. Nothing is edited directly on main. All work happens on a branch and merges in through a Pull Request (PR). This gives us a clean, auditable history and an unambiguous answer to "what's the current version?".

  main  ─●─────────────────●───────────────●──▶   (always the live/approved state)
          \               /                /
 branch:   ●──●──●  PR #12 (reviewed)      /        draft/backup-policy
                          \               /
 branch:                   ●──●  PR #13 ─/          review/access-control

The loop: 1. Branch off main for each piece of work. Name it by intent: - draft/<topic> — writing a new/updated document (e.g. draft/backup-policy) - review/<topic> — applying review fixes - fix/<topic> — small corrections, tooling, typos - One branch ≈ one document or one coherent change. Keep PRs small. 2. Commit your changes to the branch (Claude Code or git does this). 3. Open a PR into main. The PR template's checklist appears automatically. 4. CI validates the PR (tools/isms.py check) — front-matter, statuses, links, duplicate IDs. It must pass to merge. 5. Review — the ISMS owner (and/or the Thursday meeting) reviews and approves the PR. CODEOWNERS auto-requests the right reviewer. 6. Merge into main. A bot then refreshes REGISTER.md/STATUS.md so the live register always matches reality — you don't have to. 7. Delete the branch. Done.

How to know the live version of a document: - It's whatever is on main — that's the definition of "live". - Each document's front-matter version + status states its own version; a document is certification-current only when status: approved on main. - REGISTER.md on main lists every document with its current version, status, owner and next review date — the at-a-glance live picture. - Full history of any document: its git log (or "History" on GitHub). For an immutable snapshot (e.g. the exact state shown to an auditor), tag the commit: git tag audit-stage1-2026 && git push --tags.

One-time setup (Olaf, in GitHub repo settings): - Settings → Branches → Add branch protection rule for main: - ✅ Require a pull request before merging - ✅ Require approvals (1) · ✅ Require review from Code Owners - ✅ Require status checks to pass → select validate - ✅ (optional) Require branches to be up to date before merging - Edit .github/CODEOWNERS — replace @OLAF-GITHUB-HANDLE with real GitHub usernames. - Invite Andrea and Melvin with Write access (scoped to this repo only); give an auditor Read access when the time comes.

The golden rules

  1. One document = one Markdown file under docs/, organized by ISO clause.
  2. Every document starts with a front-matter block (the --- ... --- header). Copy docs/_templates/policy-template.md when creating a new one — it has all the fields.
  3. English only.
  4. Never put application source code or secrets in this repo. Policies only.
  5. Every claim must be provable. If a policy says "we enforce MFA", list under evidence: where an auditor can see it. No evidence = not real to an auditor.
  6. Keep it lean. Small company. Practical, auditable, short. Don't pad.

Writing or editing a document (two ways)

  1. Open the file on GitHub and click the pencil ✏️ (Edit) button.
  2. Make your changes in the editor.
  3. At the bottom choose "Create a new branch and start a pull request".
  4. Give it a title like Draft A.8.13 Backup Policy and submit.
  5. We review it together in the Thursday meeting and merge.

No software to install. GitHub keeps the full version history automatically.

Option B — locally with git (for Olaf / Melvin)

git switch -c draft/backup-policy
# edit files
python3 tools/isms.py check      # validate before committing
git add -A && git commit -m "Draft backup policy"
git push -u origin draft/backup-policy   # then open a PR

The document lifecycle (the status field)

template  ->  draft  ->  in-review  ->  approved
   │            │            │             │
converted   being      ready for     signed off by the
template    written    Thursday      owner; approved_by +
(not yet    by us      review        approved_date + next_review set
tailored)
  • Change status: in the front-matter as a document moves along.
  • A document only counts toward certification when it is approved.
  • When approved, also fill approved_by, approved_date, and next_review.

Before you open a PR

Just make sure validation passes:

python3 tools/isms.py check    # must show 0 errors

CI runs this automatically on every PR and flags missing front-matter, bad statuses, duplicate IDs, and broken links. You do not need to regenerate or commit REGISTER.md / STATUS.md — a bot refreshes them automatically when your PR merges to main. (If you use the /isms:* Claude Code commands they rebuild locally anyway, which is fine — but it's never required.)

Where things live

You want to… Go to
See the operating plan MASTERPLAN.md
See the certification roadmap & to-do docs ROADMAP.md
See the live list of all documents REGISTER.md (auto-generated)
See progress & what needs review STATUS.md (auto-generated)
Start a new document copy docs/_templates/policy-template.md
Get AI help drafting/reviewing prompts/

REGISTER.md and STATUS.md are generated by tools/isms.py — don't edit them by hand; edit the document front-matter and rebuild.