Tracking and managing contracts

How I track contracts in Markdown and manage the documents, including the send-for-signature loop.

I run each contract on two rails: a Markdown file that tracks the state of every workstream, and a folder that holds the actual documents. The tracker tells me where a deal stands and what is next; the folders hold the files. Both use the same workstream areas, so they mirror each other.

Tracking process (Markdown)

Each contract is tracked in one Markdown file, {client}_contract.md, separate from its documents. A # CONTRACT section holds the workstreams, and a script rolls every active contract into one shared overview.

The contract file

  • One file per deal, with YAML front matter (client, status, target close).
  • A # CONTRACT section grouped into the workstream areas: Legal, Security, Commercial, Procurement, Signature.
  • Each area lists its workstreams as ### headings (NDA, T&Cs, DPA, Order Form, and so on).

Logging activity

  • Log each event under its workstream as a plain dated line: 2026-05-20 Received redlines.
  • Lead with a verb so the status reads right: Sent / Shared / Submitted (outbound) versus Received / Client returned (inbound).
  • An optional > Next: line flags the next action.
  • Private context goes in a Note: line or a ## NOTES block and never reaches the shared overview.

Status is inferred, not typed

The latest dated line sets each workstream's status:

  • ⚪ Not started no dated line yet
  • 🔵 With us last line is inbound, so I owe the next move
  • 🟡 With client last line is outbound, so I am waiting on them
  • ✅ Complete a check mark in the workstream title
  • ⚫ N/A "N/A" in the title; excluded from all counts

The overview

A script scans every active contract file and writes one CONTRACTS.md to share with management:

  • Contracts In Progress table: one row per deal with its active + completed workstream count, the with-us / with-client / complete split, and last activity, plus a Total row.
  • Next: a prioritised action list, grouped by account.

Status and the last-activity date come from the dated log lines, so there is nothing to keep in sync by hand.

Artifacts management

The documents live in the client's folder, separate from the tracker. The tricky part is the signature stage: the "final" I send out often comes back with changes, so I separate the negotiation from the signature event.

Folder structure

One folder per contract: clients/{client}/contracts/{contract}/

  • _inbox/ raw incoming files, filed then emptied
  • legal/ NDA, MSA / T&Cs, DPA, Subprocessors, AI Addendum, SLA
  • security/ questionnaires, Panorays / OneTrust, ISO / SOC 2, pentest
  • commercial/ proposals, Order Form versions, pricing
  • procurement/ supplier registration, due diligence, insurance, tax
  • signature/ the file sent for signature plus the executed contract
  • _reference/ requirements, RFP, background

Three things, three homes

  • Negotiation (drafts, redlines, counters) stays in legal/ (and commercial/ for the Order Form). Every round is a dated file; nothing is deleted.
  • The signature event (the exact PDF sent, and the executed result) lives in signature/.
  • The timeline of the back-and-forth is logged in the contract tracker, not reconstructed from files.

Inside signature/

Keep only execution artifacts, one live at a time:

  • 260610-msa-for-signature-v1.pdf the exact PDF sent, frozen
  • 260618-msa-for-signature-v2.pdf re-sent after their changes
  • 260620-msa-EXECUTED.pdf fully signed, the source of truth, never edited
  • 260620-docusign-certificate.pdf completion certificate
  • _superseded/ voided or obsolete sent versions

The loop when changes come back

  1. Agree the draft in legal/ (latest dated file).
  2. Export to PDF as signature/...-for-signature-v1.pdf and send. Log "sent for signature".
  3. If signed: save ...-EXECUTED.pdf and the certificate. Done.
  4. If changes come back: log it, void the DocuSign envelope, move v1 to signature/_superseded/, take the edits back into legal/ as a new dated version, then export -for-signature-v2.pdf and re-send.

Negotiation never happens in signature/. It always bounces back to legal/, so signature/ only ever holds the thing being executed.

Keep it clean

  • Never edit a file in signature/. If it changes, re-export a new version from legal/.
  • Once signed, the only files outside _superseded/ are the executed PDF and its certificate.
  • Must-keep artifacts: the executed PDF and its certificate. DocuSign retains every sent and voided envelope, so the local snapshots are for offline traceability, not strictly required.