@veleads/gtm 0.4.0 → 0.7.0

package/kit/skills/01-icp/SKILL.md

@@ -1,56 +1,111 @@
 ---
 name: 01-icp
-description: Stage 1 of the gtm-brain process. Turns intake and deal evidence into icp.md (rationale), icp.yaml (machine filters consumed by scripts) and signals.yaml (signals with weight, freshness and messaging angle), plus personas, offer, proof and voice. Ends at a hard stop for ICP sign-off by the project approver.
+description: Stage 1 of the gtm-brain process. Turns research, intake and deal evidence into a layered ICP: a core profile every segment shares, 1–3 segments with what differs, personas, signals and exclusions. Writes icp.md (reasoning and hypotheses), icp.yaml (filters jobs use), signals.yaml, plus personas, offer, proof and voice. Ends at a hard stop for ICP sign-off by the project approver.
 ---
 
-# 01 · ICP research
+# 01 · ICP
 
 ## Purpose
-Define who we target and why, in a form both humans (icp.md) and code (icp.yaml, signals.yaml) use.
+Decide who we target and why, in a form people (`icp.md`) and jobs (`icp.yaml`, `signals.yaml`) both
+use. **Stage 1 ends with a decision, not certainty.** From stage 2 on, gtm-brain assumes an approved
+ICP. If you're unsure between candidates, approve the best one to three as segments and let results
+decide; revising the ICP later is normal (change it, re-approve, continue).
 
 ## Inputs
-- `context/intake.md` (especially best customers, lost deals, triggers, exclusions)
-- Won/lost deal list from the stakeholders (company names, outcome, reason). No contacts.
+- `context/research.md` (public customers, competitors, triggers) and the confirmed `context/intake.md`
+- Won/lost deals from the stakeholders (company names, outcome, reason). No contacts.
 - Schemas: `.gtm/schemas/icp.schema.json`, `.gtm/schemas/signals.schema.json`
 
+## The five layers
+
+| Layer | Question | Lives in |
+|---|---|---|
+| 1. **Core profile** | What kind of company fits *at all*? | `icp.yaml` → `core.firmographics` |
+| 2. **Segments** | Which distinct groups do we treat differently? | `icp.yaml` → `segments` (only what differs from core) |
+| 3. **Personas** | Who inside them do we contact? | `icp.yaml` → `personas`; pains and language in `personas.md` |
+| 4. **Signals** | Who is likely to buy *now*? | `signals.yaml` |
+| 5. **Exclusions** | Who must we never target? | `icp.yaml` → `exclusions` |
+
+The *why* (pains, value proposition, proof, hypotheses) is human text in `icp.md`; the YAML holds only
+what jobs filter on.
+
+## How core and segments combine
+- A segment's final filters = **core, with every field the segment sets replacing the same core
+  field.** Lists are not combined: if core says `technologies_any: [A]` and a segment says `[B]`, the
+  segment uses only `[B]`.
+- A segment can restrict `personas: [<ids>]`; otherwise it uses all personas.
+- Exclusions apply to every segment.
+- Check the result with **`npx gtm icp`**: it prints each segment's final filters and marks which fields
+  the segment set. Review that output, not the raw YAML.
+
+## Deciding core vs. segment
+- **Core** = what every good-fit company has in common: usually industry family, size band, business
+  model, required tech. If removing it from one segment would feel wrong, it belongs in core.
+- **A new segment** is justified only when something real differs:
+  - **filters** (region, sub-industry, size band, tech), and
+  - usually **treatment**: a different pain/angle, buyer, proof, language, compliance or send timezone.
+  A difference that changes neither filters nor treatment is not a segment.
+- **Regions:** make a region its own segment when language, compliance, timezone or proof differ; it
+  will usually also be its own campaign (see `02-tam`).
+- **One to three segments.** More dilutes volume per segment and makes results unreadable.
+- **Ids** are short and say who: `uk-recruitment-agencies`, `de-recruitment-agencies`.
+
 ## Steps
-1. From the best-customer list, find what the winners share: industry, size band, region, tech,
-   business model. Write evidence, not guesses (e.g. "7 of 10 best customers use Sage 200").
-2. Define 1–3 **segments**. Each segment must be expressible as filters in `icp.yaml`
-   (`industries`, `employee_count`, `hq_countries`, `technologies_any/none`, `keywords_any/none`).
-   If a criterion cannot be filtered, it belongs in `icp.md` as context, not in the YAML.
-3. Define **personas** with `role` (decision_maker / champion / influencer / user), `titles_any`,
-   `titles_none`, seniorities, departments. Write pains and language in `personas.md`.
-4. Define **signals** in `signals.yaml`: for each, `level`, `source_hint` (kind of source, never a
-   vendor), `weight` (0–100), `freshness_days`, and a `messaging_angle` copy can actually use.
-   Only include signals that change *who* or *how* we message; fewer and stronger is better.
-5. Write `offer.md` (low-friction outbound CTA) and finish `proof.md` / `voice.md` with the stakeholders.
-6. Add `exclusions`: competitor domains, excluded industries/countries.
-7. Estimate expected TAM range per segment (rough, from intake or a quick count if a TAM command is
-   available). This sets up the stage-2 sanity check.
-8. `npx gtm validate` must pass.
-9. **HARD STOP.** Present to the human for sign-off: segments + filters, personas, exclusions,
-   signals with weights, expected TAM range. Only after explicit approval from the named approver,
-   record it: `npx gtm approve icp --by "<Name (role)>" --notes "<what was approved>"`. Quote the
-   approval in the run log and commit both together.
+1. From `research.md` and intake, list what the **best customers share** (evidence, not guesses:
+   "7 of 10 best customers use Bullhorn"). These are core candidates.
+2. Group the remaining differences into **segment candidates**. For each, write in `icp.md`:
+   - **Hypothesis:** who, why they'd buy now, what proves it. _"UK agencies with 10+ open roles book
+     calls because hiring capacity is their bottleneck."_
+   - **Evidence:** wins, research, interviews.
+   - **Pain → value proposition → proof** for this segment.
+   - **Success criteria:** the number that would confirm it (e.g. "≥ 1.5 meetings per 100 contacts").
+3. Score candidates on paper (pain and urgency, ability to pay, reachability, market size, proof,
+   right to win). Drop clear losers; keep **one to three**.
+4. Write `icp.yaml`: `core.firmographics`, then `segments` with only their differences, then
+   `personas` (role, `titles_any`, **`titles_none`** to block junk, seniorities, departments) and
+   `exclusions` (competitor domains from research, excluded industries/countries). Any criterion that
+   can't be expressed as a filter stays in `icp.md` marked "context only".
+5. Write `signals.yaml`: for each signal `level`, `source_hint` (kind of source, never a vendor),
+   `weight` (0–100), `freshness_days`, and a `messaging_angle` a copywriter can use in one sentence.
+   Fewer and stronger is better.
+6. Run **`npx gtm icp`** and check every segment's final filters read as intended.
+7. Estimate the **expected TAM range per segment** (rough, from intake or research). It sets up the
+   stage-2 sanity check.
+8. Write `offer.md` (low-friction CTA) and finish `proof.md` / `voice.md` with the stakeholders.
+9. `npx gtm validate` must pass.
+10. **HARD STOP.** Present for sign-off: the `npx gtm icp` output (core + every segment's final
+    filters + personas), each segment's hypothesis and success criteria, exclusions, signals with
+    weights, expected TAM range. Record the approval:
+    - **GitHub approver** (`owners.approver` is `@handle`): commit the files on a branch, open a PR
+      (`gh pr create`), run `npx gtm track gate-open icp --pr <number>` and **stop**. After the
+      approver approves the PR on GitHub, run `npx gtm approve icp --pr <number>` (it verifies
+      the review on GitHub), commit the recorded approval and push it to the same PR branch, merge
+      once CI passes, then `npx gtm track gate-done icp`.
+    - **Named approver** (not on GitHub): present in the session; only after their explicit approval,
+      `npx gtm approve icp --by "<Name (role)>" --notes "<what was approved>"`.
+    Either way, quote the approval in the run log.
 
 ## Outputs
-`context/icp.md`, `icp.yaml`, `signals.yaml`, `personas.md`, `offer.md`, `proof.md`, `voice.md`.
+`context/icp.md` (layers, hypotheses, evidence), `icp.yaml` (core + segments + personas +
+exclusions), `signals.yaml`, `personas.md`, `offer.md`, `proof.md`, `voice.md`.
 
 ## Checklist
-- [ ] Every segment criterion in icp.md is either in icp.yaml or explicitly marked "context only"
-- [ ] Each persona has titles_none to block obvious junk (assistant, intern, interim...)
+- [ ] Core holds what every segment shares; segments hold only real differences
+- [ ] Every segment has a hypothesis, evidence and success criteria in `icp.md`
+- [ ] One to three segments; each differs in filters and (usually) treatment
+- [ ] `npx gtm icp` output reviewed: every segment's final filters read as intended
+- [ ] Each persona has `titles_none` to block obvious junk (assistant, intern, interim...)
 - [ ] Each signal has a messaging angle a copywriter could use in one sentence
-- [ ] Signal weights sum to something sensible relative to campaign tier thresholds
-- [ ] Competitors and excluded industries listed
-- [ ] icp.md and icp.yaml agree
+- [ ] Competitors (from research) and excluded industries listed
+- [ ] `icp.md` and `icp.yaml` agree; non-filterable criteria marked "context only"
 - [ ] Approval recorded with `gtm approve icp`, not by hand
 
 ## Gate
 **ICP sign-off (hard stop).** Recorded with `npx gtm approve icp`, which pins a hash of the
-approved content. Any later change to segments, personas, exclusions or other ICP content makes
-`npx gtm validate` fail until the ICP is re-presented and approved again (or the change is reverted).
-Comments and formatting do not count as changes.
+approved content (core, segments, personas, exclusions). Any later change makes `npx gtm validate`
+fail until the ICP is re-presented and approved again (or the change is reverted). Comments and
+formatting do not count as changes. Changing how volume is split between approved segments is a
+campaign decision and needs no re-approval; adding or removing a segment does.
 
 ## Next
 Create a campaign (`npx gtm new-campaign <slug>`) and go to `.gtm/skills/02-tam/SKILL.md`.

package/kit/skills/02-tam/SKILL.md

@@ -17,22 +17,27 @@ Know how big the market is, and whether the ICP filters are right, before spendi
 1. Confirm the ICP gate is approved. If not, stop and go back to `01-icp`.
 2. Set `tam_id` in `config.yaml` (`<project>-tam-<YYYYqN>` or similar). Reuse an existing `tam_id`
    if the same project already has a TAM built from the same approved ICP.
-3. Trigger the job: `npx gtm job tam <campaign>`. It reads segment filters from `icp.yaml`,
-   pulls accounts through the configured account-source adapter, writes them to `accounts`, and
-   prints counts per segment. **You do not page through accounts yourself.**
-4. Funnel counts per segment:
+3. Set `config.yaml` → `tam.source` (the account source adapter; `mock-accounts` generates fictional
+   accounts to prove the pipeline, never for a real campaign) and `tam.max_accounts_per_segment`.
+4. Trigger the job: `npx gtm job tam <campaign>`. It validates, sends segment filters and exclusions
+   from `icp.yaml` to the workers, which page accounts through the adapter, upsert them into
+   `accounts` (re-runs update, never duplicate) and print counts per segment plus a run-log row.
+   **You do not page through accounts yourself.** If it says there is no Hatchet connection, run
+   `npx gtm stack up` once (needs Docker). If that fails, or the job keeps waiting for a worker
+   (`npx gtm stack status`), stop and tell the human (AGENTS.md section 4).
+5. Funnel counts per segment (printed by the job):
    - **TAM**: accounts matching filters.
    - **Reachable**: accounts where at least one target persona can be found (from the job's
      persona count, or a sample-based estimate marked as an estimate).
    - **Active segment**: reachable minus exclusions and suppression.
-5. Sanity check: compare against the expected range. Spot-check 20 random accounts in the DB console
+6. Sanity check: compare against the expected range. Spot-check 20 random accounts in the DB console
    (name, industry, size); count how many are clearly ICP. Do not paste the rows anywhere.
-6. If the spot check finds a pattern of bad matches, propose an `icp.yaml` filter change. That
+7. If the spot check finds a pattern of bad matches, propose an `icp.yaml` filter change. That
    change resets the ICP gate, so present it to the human first.
-7. Write `tam/<tam_id>.md` from `.gtm/templates/outputs/tam-summary.md` and the run log.
+8. Write `tam/<tam_id>.md` from `.gtm/templates/outputs/tam-summary.md` and the run log.
 
 ## Outputs
-- Rows in `accounts` (Postgres), tagged `project_id`, `tam_id`, `run_id`.
+- Rows in `accounts` (this project's Postgres), tagged `tam_id`, `segment_id`, `run_id`.
 - `tam/<tam_id>.md` with funnel table and sanity check. Run log.
 
 ## Checklist

package/kit/skills/05-copy/SKILL.md

@@ -28,9 +28,15 @@ the approver signed off.
 5. Self-review against the checklist below, then render each step once with a fictional example
    lead (fictional name and company) for the human.
 6. **HARD STOP.** Present all variants for sign-off. Edits requested → change, re-present,
-   still pending. Only after explicit approval from the named approver, record it:
-   `npx gtm approve copy <campaign> --by "<Name (role)>" --notes "<what was approved>"`. Quote the
-   approval in the run log and commit `copy.md`, `config.yaml` and the run log together.
+   still pending. Record the approval:
+   - **GitHub approver** (`owners.approver` is `@handle`): commit the files on a branch, open a PR
+     (`gh pr create`), run `npx gtm track gate-open copy <campaign> --pr <number>` and **stop**. After the
+     approver approves the PR on GitHub, run `npx gtm approve copy <campaign> --pr <number>` (it verifies
+     the review on GitHub), commit the recorded approval and push it to the same PR branch, merge
+     once CI passes, then `npx gtm track gate-done copy <campaign>`.
+   - **Named approver** (not on GitHub): present in the session; only after their explicit approval,
+     `npx gtm approve copy <campaign> --by "<Name (role)>" --notes "<what was approved>"`.
+   Either way, quote the approval in the run log.
 
 ## Outputs
 `copy.md` (status line at top reflects the gate). Run log.

package/kit/skills/07-launch/SKILL.md

@@ -17,7 +17,7 @@ Get the approved leads and copy into the sender safely, and start sending only o
    sequence from `copy.md`, pushes leads in send tiers, sets the schedule from `sending`. Write the
    returned reference into `config.yaml` → `sending.sender_campaign_ref`.
 3. Read the push counts: accepted vs. rejected (with reasons). Rejections > 2% → investigate first.
-4. **HARD STOP: go/no-go.** Present: leads pushed by tier, daily volume and ramp, first send
+4. Run `npx gtm track gate-open launch <campaign>`. **HARD STOP: go/no-go.** Present: leads pushed by tier, daily volume and ramp, first send
    date/time, spend so far vs. cap, QA summary, sender campaign ref (paused). Ask the campaign owner
    or GTM engineer for an explicit go. Record in `config.yaml` → `gates.launch` per AGENTS.md section 4.
 5. Only after approval: `npx gtm job activate <campaign>`. Set `stage: results`.

package/kit/skills/research/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: research
+description: Researches the business this project runs outbound for (product, pricing, positioning, public customers, competitors, buying triggers) from public sources before anyone is asked questions. Writes context/research.md with a source URL for every claim. Used first in stage 00-intake and re-run before new campaigns or when the market changes.
+---
+
+# Research: the business, its customers and competitors
+
+## Purpose
+Do the homework so stakeholders are only asked what research can't answer. Every fact is sourced,
+so nothing invented reaches the ICP or the copy.
+
+## Inputs
+- The business name and website (from `project.yaml` → `name`, or ask for the URL; that is the only
+  question allowed before researching).
+- Existing `context/research.md` when re-running (update it; keep the history section).
+
+## Rules
+1. **Source every claim** with a URL in the same line. No source → it doesn't go in.
+2. **Public information only.** No paywalled content, no logging in, no scraping behind forms.
+3. **Companies, not people.** Record company names and domains. Do not collect names, emails or
+   profiles of individuals (prospect data belongs in Postgres via jobs, never in git).
+4. **Don't guess.** Unknown is a valid answer; mark it `unknown` and list it under open questions.
+5. **Mark confidence:** `confirmed` (the business's own site says it), `likely` (credible third
+   party: reviews, press), `inferred` (your reading of several sources; say why).
+6. **No web access?** Ask the human for the website URL and to paste the text of the home, product,
+   pricing and customers pages, then work from that and say so in the file.
+
+## Steps
+1. **The business:** home, product/solutions, pricing, customers/case studies, about, careers,
+   blog/news. Capture: what they sell (one sentence), who it is for, pricing model and visible price
+   points, proof points with numbers, positioning words they repeat.
+2. **Public customers:** logos and case studies on their site, plus credible mentions (press,
+   reviews). For each: company name, domain, industry/size/region/tech if visible, source. These are
+   **suppression candidates** (don't cold-email customers) and the main input for the ICP layers:
+   - **Core candidates:** traits most customers share (industry family, size band, required tech,
+     business model). Say how many share it ("7 of 10 use Bullhorn").
+   - **Segment candidates:** clusters that differ in a filter *and* in treatment (region/language,
+     sub-industry, size band, buyer). For each: the cluster, its members, and why it might need a
+     different angle.
+3. **Competitors (3–5):** from "alternatives to <business>" searches, review-site categories and
+   comparison pages. For each: domain, one-line positioning, pricing if public, how the business
+   differs. These are **exclusion candidates** for `icp.yaml`.
+4. **Market and triggers:** what makes a company buy now (hiring for X, new leader, funding,
+   migration, regulation), with sources. These seed `signals.yaml`.
+5. **Write `context/research.md`** from `.gtm/templates/project/research.md`.
+6. **Summarise for the human** in 5 lines: what you found, the strongest ICP hint, top competitors,
+   and the open questions only they can answer.
+
+## Outputs
+`context/research.md`: sourced facts, customers (suppression candidates), **core candidates** and
+**segment candidates** for the ICP, competitors (exclusion candidates), triggers (signal candidates),
+open questions. Candidates are suggestions until a
+stakeholder confirms them in intake or ICP.
+
+## Checklist
+- [ ] Every claim has a URL and a confidence mark
+- [ ] No individuals' personal data
+- [ ] Customers and competitors listed with domains
+- [ ] Open questions listed (only what research can't answer)
+
+## Next
+Back to `.gtm/skills/00-intake/SKILL.md` (draft intake from research), or the stage that asked for a refresh.

package/kit/stack/docker-compose.yml

@@ -0,0 +1,66 @@
+# One project's stack: Postgres (this project's data + Hatchet's state), hatchet-lite (job engine) and
+# the gtm worker at the core version this project repo pins. Driven by `npx gtm stack up|down|status`,
+# which sets the compose project name (gtm-<project_id>), the ports and the worker image.
+# Data stays in this project's Docker volumes; nothing here is written into the repo.
+services:
+  postgres:
+    image: postgres:16.10
+    command: postgres -c max_connections=200
+    environment:
+      POSTGRES_USER: gtm
+      POSTGRES_PASSWORD: gtm
+      POSTGRES_DB: gtm
+    # Local only: reachable from this machine (QA samples in a DB console), not from the network.
+    ports: ["127.0.0.1:${GTM_PG_PORT:-5432}:5432"]
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./init:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U gtm -d gtm"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  hatchet-lite:
+    image: ghcr.io/hatchet-dev/hatchet/hatchet-lite:v0.110.5
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${GTM_HATCHET_UI_PORT:-8888}:8888"
+      - "127.0.0.1:${GTM_HATCHET_GRPC_PORT:-7077}:7077"
+    environment:
+      DATABASE_URL: postgresql://gtm:gtm@postgres:5432/hatchet?sslmode=disable
+      SERVER_AUTH_COOKIE_DOMAIN: localhost
+      SERVER_AUTH_COOKIE_INSECURE: "t"
+      SERVER_GRPC_BIND_ADDRESS: 0.0.0.0
+      SERVER_GRPC_INSECURE: "t"
+      SERVER_GRPC_BROADCAST_ADDRESS: localhost:${GTM_HATCHET_GRPC_PORT:-7077}
+      SERVER_GRPC_PORT: "7077"
+      SERVER_URL: http://localhost:${GTM_HATCHET_UI_PORT:-8888}
+      SERVER_AUTH_SET_EMAIL_VERIFIED: "t"
+      SERVER_INTERNAL_CLIENT_INTERNAL_GRPC_BROADCAST_ADDRESS: localhost:7077
+    volumes:
+      - hatchet_config:/config
+
+  worker:
+    image: ${GTM_WORKER_IMAGE:-ghcr.io/veleads/gtm-worker:latest}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      hatchet-lite:
+        condition: service_started
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgresql://gtm:gtm@postgres:5432/gtm
+      HATCHET_CLIENT_TOKEN: ${HATCHET_CLIENT_TOKEN:-}
+      HATCHET_CLIENT_HOST_PORT: hatchet-lite:7077
+      HATCHET_CLIENT_TLS_STRATEGY: none
+    # Provider API keys: ~/.gtm/stacks/<project_id>.secrets.env, outside the repo. Optional.
+    env_file:
+      - path: ${GTM_SECRETS_FILE:-/dev/null}
+        required: false
+
+volumes:
+  pgdata:
+  hatchet_config:

package/kit/stack/init/01-hatchet-db.sql

@@ -0,0 +1,2 @@
+-- hatchet-lite keeps its own state in a separate database on the same Postgres instance.
+CREATE DATABASE hatchet;

package/kit/templates/campaign/config.yaml

@@ -5,6 +5,9 @@ campaign_id: __CAMPAIGN_ID__
 owner: __OWNER__
 stage: icp
 tam_id: __PROJECT_ID__-tam-TODO
+tam:
+  source: mock-accounts # mock-accounts proves the pipeline locally; replace with a real account source
+  max_accounts_per_segment: 500
 segments: [segment-one]
 personas: [persona-one]
 

package/kit/templates/project/icp.md

@@ -1,15 +1,51 @@
 # ICP: __PROJECT_NAME__
 
-> Human-readable rationale. The machine-readable version is `icp.yaml`. Keep them in sync.
+> Written in stage `01-icp` from `research.md`, intake and won/lost deals. This file holds the *why*;
+> `icp.yaml` holds the filters jobs use. Keep them in sync, and review the final filters with
+> `npx gtm icp`. Mark anything that can't be a filter as **(context only)**.
 
-## Who buys
+## Summary
+One paragraph: who we sell to, the problem we solve for them, and why now.
 
-## Segments
-1. **<segment-id>**: description and evidence (win rate, cycle length, deal size).
+## 1. Core profile (every segment)
+What every good-fit company has in common, with evidence.
 
-## Personas
-- **<persona-id> (role):** titles, why they care.
+| Criterion | Value | Evidence |
+|---|---|---|
+| Industry family | | _e.g. 8 of 10 best customers are staffing agencies_ |
+| Size band | | |
+| Business model | | (context only, if not filterable) |
+| Required tech | | |
 
-## Why they buy (evidence from won deals)
+## 2. Segments
+One to three. Each differs from core in filters **and** (usually) treatment.
 
-## Exclusions
+### <segment-id>
+- **Who (filters beyond core):** _e.g. HQ in GB_
+- **Hypothesis:** who, why they'd buy now, what proves it.
+  _"UK agencies with 10+ open roles book calls because hiring capacity is their bottleneck."_
+- **Evidence:** wins, research, interviews.
+- **Pain → value proposition → proof:**
+- **Buyer / personas:** all, or only <persona-ids>
+- **Treatment:** language, compliance basis, send timezone, offer differences (if any)
+- **Expected TAM range:** _e.g. 2,000–4,000 companies_
+- **Success criteria:** _e.g. ≥ 1.5 meetings per 100 contacts after 300 contacts_
+
+## 3. Personas
+- **<persona-id> (decision_maker / champion / influencer / user):** titles, what they care about.
+  Details and language in `personas.md`.
+
+## 4. Signals (why now)
+The triggers in `signals.yaml`, in plain words, with the angle each gives the copy.
+
+## 5. Exclusions
+- Competitors (from `research.md`):
+- Excluded industries / countries:
+- Existing customers and open deals: loaded as suppression lists (never written here).
+
+## Candidates considered and dropped
+| Candidate | Why dropped |
+|---|---|
+
+## Decision log
+- <YYYY-MM-DD>: first ICP drafted.

package/kit/templates/project/icp.yaml

@@ -1,21 +1,30 @@
 # yaml-language-server: $schema=../.gtm/schemas/icp.schema.json
+# Layers: core (every segment) → segments (only what differs) → personas → exclusions. Signals live in
+# signals.yaml. A segment field REPLACES the same core field. Review the result with `npx gtm icp`.
 version: 2
 project_id: __PROJECT_ID__
 approval:
   status: pending # only a named human approves (AGENTS.md hard stop)
   approved_by: null
   approved_at: null
+core:
+  firmographics:
+    industries: [TODO] # what every good-fit company shares
+    employee_count: {min: 20, max: 500}
 segments:
   - id: segment-one
-    description: TODO
+    description: TODO # who, in a few words
     firmographics:
-      industries: []
-      employee_count: {min: 50, max: 1000}
-      hq_countries: []
+      hq_countries: [] # only what differs from core, e.g. [GB]
+  # - id: segment-two
+  #   description: ...
+  #   firmographics: {hq_countries: [DE, AT, CH], employee_count: {min: 50, max: 1000}}
+  #   personas: [persona-one]   # optional: restrict personas for this segment
 personas:
   - id: persona-one
     role: decision_maker
     titles_any: [TODO]
+    titles_none: [Assistant, Intern]
     seniorities: []
     departments: []
 exclusions:

package/kit/templates/project/intake.md

@@ -1,29 +1,44 @@
 # Intake: __PROJECT_NAME__
 
-> Stage 0 output. Fill every section; write "unknown" rather than leaving blanks.
+> Stage 0 output. Drafted from `context/research.md` first; stakeholders only answer what research
+> couldn't. Mark each field `(researched: <source>; confirm)`, `(confirmed by <who>)` or `(needs you)`.
+> Write "unknown" rather than leaving blanks.
 
 ## Company
 - **What they sell (one sentence):**
+  _e.g. "Outbound lead generation for B2B SaaS, delivered as a managed service."_
 - **Website:**
-- **ACV / sales cycle / sales motion:**
+- **Deal size, sales cycle and motion:** average first-year value, days from first call to signature,
+  and how deals close.
+  _e.g. "~$15k/year, 30–45 days, founder-led demo then proposal."_
 - **Current customers (count, typical size, industries, regions):**
 - **Why outbound now:**
 
 ## Goals
-- **Target (meetings / pipeline) and timeframe:**
-- **Meeting definition (who, what qualifies):**
+- **Target and timeframe:** a number you can check later.
+  _e.g. "20 qualified meetings in 60 days."_
+- **What counts as a meeting:** who must attend and what makes it qualified.
+  _e.g. "Head of Sales or founder at a 20–200 person SaaS company books a 30-min call."_
 
-## Questionnaire
-1. Top 10 best customers. Why did each buy? (company names only, no contacts)
+## Owners and regions
+(Recorded in `project.yaml`, explained here.)
+- **GTM engineer:** runs the agent and the jobs. _e.g. "@abdullah"_
+- **SDRs:** handle replies and booked meetings. _e.g. "@sara", or "none yet"_
+- **Approver:** says yes to the ICP and the copy before anything is sent. Must not be the person who
+  opens the PRs (GitHub doesn't allow approving your own PR). _e.g. "@maria (co-founder)"_
+- **Regions:** where prospects are; drives privacy rules (GDPR for UK/EU) and TAM filters.
+  _e.g. "UK and US"_
+
+## Questionnaire (research pre-fills what it can)
+1. Best customers (up to 10, company names only). Why did each buy?
 2. Last 5 lost deals. Why did each lose?
-3. Who signs, who champions, who blocks?
+3. Who signs, who champions, who blocks? (roles, not names)
 4. Top 3 competitors and how you win against each.
 5. Triggers that make a prospect buy now (hiring, funding, new leader, migration...).
 6. Proof you can use in outbound (case studies, numbers, logos) and what is off-limits.
 7. Tone: words you love, words you hate.
-8. Regions you can legally and commercially serve.
-9. Previous outbound: what was sent, results, which lists.
-10. Anyone or anything we must never contact.
+8. Previous outbound: what was sent, results, which lists.
+9. Anyone or anything we must never contact.
 
 ## Constraints
 -
@@ -40,4 +55,4 @@
 | Calendar / booking link | stakeholder | |
 | Lawful basis documented (LIA for EU/UK legitimate interest) | stakeholder + GTM team | |
 | Privacy notice URL | stakeholder | |
-| Named approver for ICP + copy | stakeholder | |
+| GitHub: owners added to the repo; `npx gtm github setup --apply` run | GTM team | |

package/kit/templates/project/project.yaml

@@ -4,9 +4,13 @@ project_id: __PROJECT_ID__
 name: __PROJECT_NAME__
 status: onboarding
 started_at: __TODAY__
+# Owners: use GitHub handles (@username). An approver handle makes ICP/copy sign-off a PR review that
+# GitHub enforces (CODEOWNERS). Use a plain name only for an approver who isn't on GitHub.
 owners:
-  gtm_engineer: TODO
-  sdrs: []
-  approver: TODO # person who signs off ICP and copy for this project
-regions: [TODO]
+  gtm_engineer: TODO # e.g. "@abdullah": runs the agent and jobs
+  sdrs: [] # e.g. ["@sara"]: handle replies and meetings
+  approver: TODO # e.g. "@maria": signs off ICP and copy
+regions: [TODO] # where prospects are, e.g. [UK, US]
 features: {} # opt-in core features (see .gtm/ CHANGELOG / FEATURES)
+tracker:
+  kind: github # mirror stages and gates as GitHub issues (`npx gtm track`); "none" to switch off

package/kit/templates/project/research.md

@@ -0,0 +1,45 @@
+# Research: __PROJECT_NAME__
+
+> Written by the `research` skill. Every claim has a source URL and a confidence mark
+> (confirmed / likely / inferred). Candidates are suggestions until a stakeholder confirms them.
+> Companies only: no individuals' personal data.
+
+- **Researched on:** <YYYY-MM-DD> by <agent / person>
+- **Website:**
+- **Web access:** yes / no (worked from pasted page text)
+
+## The business
+| Fact | Value | Source | Confidence |
+|---|---|---|---|
+| What they sell (one sentence) | | | |
+| Who it's for | | | |
+| Pricing model / price points | | | |
+| Proof points (numbers) | | | |
+| Positioning words they repeat | | | |
+
+## Public customers (suppression candidates)
+| Company | Domain | Industry / size | Source |
+|---|---|---|---|
+
+### ICP hints
+**Core candidates** (traits most customers share):
+| Trait | How many customers share it | Source |
+|---|---|---|
+
+**Segment candidates** (clusters that differ in filters and treatment):
+| Cluster | Differs by | Members | Why it may need its own angle |
+|---|---|---|---|
+
+## Competitors (exclusion candidates)
+| Competitor | Domain | Positioning | Pricing | How we differ | Source |
+|---|---|---|---|---|---|
+
+## Buying triggers (signal candidates)
+| Trigger | Why it matters | Source |
+|---|---|---|
+
+## Open questions (only stakeholders can answer)
+-
+
+## History
+- <YYYY-MM-DD>: first research

package/kit/templates/repo/README.md

@@ -10,6 +10,7 @@ npm install          # or: pnpm install / yarn install
 cp .env.example .env
 npx gtm status
 npx gtm validate
+npx gtm stack up     # this project's own stack (needs Docker); jobs run on it
 ```
 
 ## What lives where
@@ -22,3 +23,7 @@ npx gtm validate
 ## Core upgrades
 A weekly workflow opens a PR when a new core is released (`.github/workflows/gtm-upgrade.yml`).
 Manually: `npx gtm upgrade` (refuses while a campaign is between QA and launch).
+
+## GitHub
+Approvals and tracking run through GitHub: see `.gtm/guides/github.md` (owners as `@handles`,
+`npx gtm github setup --apply`, PR-based sign-off, the org-wide board).

package/kit/templates/repo/env.example

@@ -1,5 +1,5 @@
-# Copy to .env (never commit). Provider API keys do NOT belong here: they live on the central worker.
+# Copy to .env (never commit). Provider API keys do NOT belong here: they go to this project's worker
+# (local stack: ~/.gtm/stacks/<project_id>.secrets.env). `npx gtm stack up` writes the connection
+# settings to ~/.gtm/stacks/<project_id>.env; set HATCHET_CLIENT_TOKEN here only for a hosted stack.
 GTM_USER=jdoe
-# Phase 2: trigger jobs on the shared Hatchet, read-only DB access for QA samples
 HATCHET_CLIENT_TOKEN=
-DATABASE_URL_READONLY=

package/kit/templates/repo/github/workflows/gtm.yml

@@ -6,6 +6,7 @@ on:
 
 permissions:
   contents: read
+  pull-requests: read # gtm validate --verify-github reads PR reviews
 
 jobs:
   check:
@@ -25,5 +26,7 @@ jobs:
           fi
       - name: Core files untouched and in sync
         run: npx gtm sync --check
-      - name: Validate project repo
-        run: npx gtm validate
+      - name: Validate project repo (and verify GitHub approvals)
+        run: npx gtm validate --verify-github
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}