---
name: contracts
description: Orchestrate the full lifecycle of Gemma contracts and proposals -- scaffolding, Typst compilation, iteration, and git workflow for FSA, NDA, DPA, amendment, offer, retainer, and proposal documents.
---

# Contracts Workflow

This skill orchestrates the full lifecycle of creating documents in the Gemma contracts repo: scaffolding, writing, compiling, iterating on feedback, and finalizing.

## Scope

This skill applies exclusively to work in the `Gemma-Analytics/contracts` repo. The workflows, branching conventions, commit patterns, and compilation steps described here are specific to that repo. Do not apply them to other repositories or tasks.

## When to activate

Activate when the conversation involves creating or editing Gemma contracts or proposals. Common triggers:
- "Create a proposal for X"
- "Draft an NDA for X"
- "Let's put together an offer for X"
- "Continue working on the Acme contracts"
- Any mention of contract types: FSA, NDA, DPA, amendment, offer, proposal, retainer

Do not activate for general document editing, non-Gemma contracts, or conversations that happen to mention contracts in passing.

## Document type disambiguation

The repo has 7 document types. Two are commonly confused:

- **Proposal** (`proposal` type) -- a non-binding visual sales document for client stakeholders to evaluate. Long, detailed, includes work streams, timelines, pricing, approach. Uses the `gemma-proposal` show-rule with accent bars and visual components.
- **Offer** (`offer` type) -- a short legal document for actual contract signature. Formal, concise. May reference a proposal as an appendix.

Users may say "offer" when they mean "proposal" and vice versa. When ambiguous, ask: "Do you mean a detailed proposal document for stakeholders to review, or a short formal offer for signature?"

Other types are less ambiguous:
- **FSA** -- Framework Service Agreement (main consulting contract)
- **NDA** -- Confidentiality agreement
- **DPA** -- GDPR data processing agreement
- **Amendment** -- Modification to an existing contract
- **Retainer** -- Ongoing monthly engagement terms

## Setup

### Clone or pull the contracts repo

On first use in a session, clone the repo. On subsequent use, pull latest.

```bash
git clone https://github.com/Gemma-Analytics/contracts <contracts_repo_path>
```

### Read the repo's CLAUDE.md

Always read `CLAUDE.md` in the contracts repo root before doing any work. It contains the authoritative rules for config patterns, template architecture, compilation, naming conventions, and session pitfalls. Follow it exactly.

### Build the Docker image

```bash
./run.sh build
```

This only needs to happen once per session. The Docker image pins the Typst version used in CI.

### Set up PDF delivery

After each compile, the user needs to see the PDF. Prefer serving over HTTP when available -- it gives the user a stable URL that updates on each recompile, and avoids re-uploading files on every iteration.

- **Serve over HTTP (preferred)**: If you can host files (e.g. a dev server, reverse proxy, or process registration), serve the compiled PDF at a stable URL. Set this up once before the first compile so the user gets a live link immediately. On each recompile, the same URL serves the updated PDF.
- **Point to the file on disk (fallback)**: If HTTP hosting is not available, tell the user the path to the compiled PDF in `clients/<client_slug>/out/`.

If the user expresses a preference for a different delivery method, follow their lead -- this is a default, not a mandate.

Either way, also visually inspect the PDF yourself using the `pdf-to-png.py` script described in the repo's CLAUDE.md Session Pitfalls. This lets you catch layout issues before the user sees the document.

## Phase 1: Start

### 1. Check for existing work

Before scaffolding, check if a `drafts/<client_slug>` branch already exists:

```bash
git branch -r | grep "drafts/"
```

If a branch exists for this client, ask the user if they want to continue that work or start fresh. If multiple branches exist, list them and ask which one.

If continuing: check out the branch and skip to the iteration phase.

### 2. Create or switch to a drafts branch

```bash
git checkout -b drafts/<client_slug>
```

Use the client slug (lowercase, hyphens, no special characters) -- the same slug that `run.sh new-contract` generates. One branch per client, not per document type. Multiple document types for the same client go on the same branch.

### 3. Scaffold the document

```bash
./run.sh new-contract "<client_name>" <type> <language>
```

Always use this script. It creates the directory structure, copies the right template, and generates config files.

### 4. Gather client information

For `client.yaml`, you need: legal company name, court/registry (for German companies), address, signer name and title.

**Do not assume or guess any of these values.** Instead:
1. Search the web for the company (official website, Handelsregister, LinkedIn)
2. Fill in what you find
3. Present your findings to the user and ask them to confirm or correct

For config values (dates, rates, scope, modules), ask the user. Never fill in placeholder values silently.

#### Gemma signer

Ask who signs for Gemma on this document -- do not assume the default without asking. Options:

- **Bijan Soltani** -- Geschäftsführer (DE) / Managing Director (EN). This is the default from `apply-defaults()` in the contracts repo; no `gemma:` override needed if he signs.
- **Bianca Frost** -- ppa. Bianca Frost, Managing Principal (same title in both DE and EN documents)
- **David Bader** -- ppa. David Bader, Managing Principal (same title in both DE and EN documents)

If Bianca or David signs, override the `gemma:` block in `client.yaml`:

```yaml
gemma:
  signer_name: "<signer_name>"  # e.g. "Bianca Frost" or "David Bader"
  signer_title: "Managing Principal"
  ppa: true
```

### 5. Read and process context

Read any files the user has attached or text they've pasted (call notes, email threads, client briefs). Generate a `context.md` in the client directory that captures:

- **Client situation**: what they need and why
- **Key constraints**: budget, timeline, decision-makers, sensitivities
- **Scope decisions**: what's in, what's explicitly out, and why
- **Open questions**: things still unresolved
- **Internal dynamics**: who the document has to convince inside the client's organization, stakeholder politics, and any required framing (e.g. "enable, don't replace" toward an incumbent service provider). Proposals often double as the champion's internal sales material -- these dynamics shape wording in every later round.

Post the `context.md` content in the conversation for the user to review and correct. Update it whenever significant new context emerges during iteration.

`context.md` is committed to git alongside the document source. Raw context files (transcripts, emails) are not committed.

### 6. Write the document content

Fill in the `.typ` file based on the context, user input, and template structure. Follow all rules in the repo's CLAUDE.md -- especially:
- Never rewrite legal prose without explicit instruction
- Use the clause library before writing new legal text
- Keep client-specific logic out of templates
- Use the config YAML for all variable data

### 7. Compile and preview

```bash
./run.sh compile clients/<client_slug>/<file>.typ
```

Always compile via Docker, never with a local Typst install. Deliver the compiled PDF to the user (see "Set up PDF delivery" above). Visually inspect the output yourself before telling the user it's ready.

### 8. Commit work-in-progress

```bash
git add clients/<client_slug>/
git commit -m "<client_slug>: draft <type> (<language>)"
git push -u origin drafts/<client_slug>
```

Commit after every meaningful change so the work survives across sessions.

## Phase 2: Iterate

1. User gives feedback
2. Update the `.typ` file and/or config YAML
3. Recompile via Docker: `./run.sh compile clients/<client_slug>/<file>.typ`
4. Deliver the updated PDF to the user and visually inspect it yourself
5. If context changed, update `context.md` and post it in the conversation
6. Commit and push to the drafts branch

Repeat until the user is satisfied. Each iteration is a commit on the branch.

### Iterating after a client meeting

When a feedback round follows a client meeting, ground the edits in what was actually said:

1. **Ingest the meeting record first** (transcript or AI-generated notes -- check the client's `contextdrop/` folder or the user's Google Drive), then make all edits in one pass. If the record is temporarily unreachable (e.g. connector auth trouble), don't block: apply the changes the user specified, note the pending ingestion in `context.md`, and do a second pass once it's readable.
2. **Resolve discussion points instead of deleting them.** Callouts that framed open questions for the meeting become a resolved/open status after it (e.g. a "Geklärt" callout and an "Offen" callout) -- the resolution is sales-relevant content, not clutter.
3. **Sweep for stale time references.** Phrases like "stimmen wir im Termin ab" or a start date the meeting invalidated read as unmaintained once the meeting has happened. Check dates, validity windows, and every mention of the meeting itself.

### Resuming work

If this is a new session resuming previous work:
1. Clone/pull the repo
2. Check out the drafts branch: `git checkout drafts/<client_slug>`
3. Build the Docker image
4. Compile the current state and deliver the PDF so the user can see where things stand
5. Continue iterating

If the drafts work was already squash-merged or PR-merged to main and a new feedback round arrives, recreate the branch from the current remote tip -- this works whether or not `drafts/<client_slug>` still exists locally or on the remote (Phase 3 cleanup may have deleted it, or a merge without cleanup may have left it stale):

```bash
git fetch origin
git checkout -B drafts/<client_slug> origin/main
git push -u --force-with-lease origin drafts/<client_slug>
```

One branch per client still holds across merge cycles.

## Phase 3: Finalize

When the user says the document is done ("finalize", "done", "ready to send", "this is good", or similar):

### 1. Final compile

Compile one last time to ensure the PDF is current.

### 2. Squash merge to main

```bash
git checkout main
git pull origin main
git merge --squash drafts/<client_slug>
git commit -m "<client_slug>: finalize <type> (<language>)"
git push origin main
```

The squash merge collapses all iteration commits into one clean commit on main.

### 3. Deliver the final PDF

Give the user the final compiled PDF -- upload it to the conversation or tell them the file path.

### 4. Clean up the branch

```bash
git push origin --delete drafts/<client_slug>
git branch -d drafts/<client_slug>
```

### 5. Post the final context.md

Post the final `context.md` content in the conversation so there's a record of the context that shaped the document.

## Working on multiple document types

A single client branch can accumulate multiple documents. For example, a user might ask for an FSA, NDA, and proposal in sequence:

```bash
# All on the same branch
./run.sh new-contract "Acme Corp" fsa en
# ... iterate on FSA ...
./run.sh new-contract "Acme Corp" nda bilingual
# ... iterate on NDA ...
./run.sh new-contract "Acme Corp" proposal en
# ... iterate on proposal ...
```

The `client.yaml` is shared across all document types for that client. Each type gets its own `config-<type>.yaml` and `.typ` file.

Finalization can happen per-document or for the whole batch -- follow the user's lead.

## Key principles

- **Ask, don't assume.** Never fill in client details, dates, rates, or legal text without user confirmation. Search the web proactively, but always confirm findings.
- **CLAUDE.md is authoritative.** The contracts repo's CLAUDE.md has the final word on config patterns, template architecture, compilation, and naming. This skill handles workflow orchestration only.
- **Compile via Docker only.** Never use a local Typst install. The Docker image pins the exact version used in CI.
- **Commit often.** Every meaningful change gets committed to the drafts branch. This enables session continuity.
- **Context.md is the memory.** It's the distilled understanding of why the document looks the way it does. Keep it updated and share it with the user.