Naming

Naming Skill

A structured workflow for naming one product, one company, or one brand where product and company share the same name. Uses multi-model ensemble (Claude + optional Codex / Gemini) to generate diverse candidates, filters through a two-layer rubric (Gate + Score), tests with real humans, and produces a finalist.

Scope

• One entity per run. Name one product, one company, or one brand where product and company share the same name (treated as a single entity).
• Separate entities → run twice. If product and company need different names, run the skill once for each. Do not merge briefs.
• Language: English-first. Non-English markets handled only as gate check, not name generation.
• Out of scope: multi-product portfolio governance (brand architecture, nomenclature systems). See references/out-of-scope.md.

Output

5 Markdown files in {repo}/docs/naming/ plus a state file and test kit:

docs/naming/
├── naming-state.yaml        # Session state (internal)
├── 01-brief.md               # Benefit ladder, personality, constraints
├── 02-namescape.md           # Competitive naming map + no-go zones
├── 03-candidates.md          # All candidates grouped by taxonomy + source model
├── 04-evaluation.md          # Gate survivors + score rubric
├── test-kit.md               # Phase 5 tension test materials (printable)
├── 05-decision.md            # Final choice, rationale, limitations, announcement
└── .raw/                     # Raw model outputs + briefs (per-session, timestamped)

Document schemas — see references/templates.md for the full markdown template of each output file. Every phase output must match the template so outputs are consistent across sessions and can be audited or diffed.

Taxonomy Reference (11 Types)

Full definitions and examples: references/taxonomy.md. Phases 2 and 3 both depend on this list:

1. Descriptive · 2. Suggestive / Evocative · 3. Invented / Coined ·
2. Metaphorical · 5. Real word out of context · 6. Compound ·
3. Portmanteau · 8. Greek / Latin root · 9. Founder · 10. Acronym ·
4. Misspelled / Truncated.

Phase 2 uses it to classify competitors. Phase 3 uses it as the generation palette. Always load references/taxonomy.md before either phase runs.

First-Run Flow (Mode Ordering)

The state file can only be created after the user tells us whether this is a greenfield or a rebrand. Order of operations on first run:

1. Ask the Starting Context question (A/B/C) below.
2. Ask the Entity Scope question (product / company / both-same-name) below.
3. Derive mode from the Starting Context answer: A or B → greenfield, C → rebrand.
4. Create docs/naming/naming-state.yaml with:
   • mode: derived from step 3
   • entity_scope: from step 2 answer
   • overall_status: matching the mode (brief for greenfield, rebrand_audit for rebrand) Do not hard-code any of these before the user answers.
5. Check for docs/gtm/gtm-state.yaml (see GTM Integration).
6. If rebrand, run Phase 0; otherwise start at Phase 1.

Starting Context question

What's your situation?

• A) I have an idea but no code yet.
• B) I have code (or a working product) but no name — or just a placeholder.
• C) I have code and a name, but I want to consider a rebrand.

• A → mode: greenfield, skip codebase scan, go to Phase 1.
• B → mode: greenfield, light codebase scan (README, package.json, top-level dirs) to pre-fill product description, then Phase 1.
• C → mode: rebrand, run Phase 0 first.

Entity Scope question

What are you naming?

• product — one specific product. Company already has a name.
• company — the company / parent brand. Products stay separate.
• both_same_name — company and flagship product share a single name (e.g., Notion, Linear, Figma). Treated as one naming exercise.

Record the answer in entity_scope. This shapes Phase 1 brief framing (company-level mission/vision vs product-level feature focus) and Phase 6 Final Selection deliverables.

Modes

State Management

After the Starting Context answer, create docs/naming/naming-state.yaml:

project: {repo name}
repo_path: {absolute path}
created: {YYYY-MM-DD}
last_updated: {YYYY-MM-DD}

mode: {greenfield|rebrand}     # derived from Starting Context
entity_scope: product          # product | company | both_same_name
starting_context: B            # A | B | C
has_gtm_docs: false

# Top-level enum — must be exactly one of:
# rebrand_audit | brief | namescape | generate | evaluate | tension_test |
# decision | complete | ended_no_change
#
# Initial value depends on mode:
# - greenfield → overall_status: brief
# - rebrand    → overall_status: rebrand_audit  (Phase 0 must run first)
overall_status: brief           # or rebrand_audit when mode: rebrand

# Available model ensemble for Phase 3 generation (filled after detection)
models_available:
  claude: true
  codex: false
  gemini: false
models_selected: [claude]      # user's choice from available models
candidates_per_model: 100      # user-tunable

phases:
  rebrand_audit:                # only in rebrand mode
    status: pending
    triggers_confirmed: []
    decision: null              # keep | change
  brief:
    status: pending
  namescape:
    status: pending
  generate:
    status: pending
    candidate_count: 0
    by_model: {}                # claude: 100, codex: 100, ...
  evaluate:
    status: pending
    gate_survivors: 0
    scored: 0
  tension_test:
    status: pending             # pending | kit_ready | awaiting_user_results | complete | skipped_low_sample
    tester_count: 0
  decision:
    status: pending

findings:
  benefit_ladder: {}            # feature / functional / emotional / ultimate
  ultimate_concept: ""          # 1-2 word creative springboard
  personality: {}
  constraints: {}
  competitors: []
  no_go_patterns: []
  winner: ""

disputes: []                    # any user disagreement; see Dispute Handling

# Fallback flags — any "unverified" entry bubbles up to 05-decision.md Limitations
unverified:
  trademark: []
  domain: []
  handles: []
  cross_cultural: []

Naming note: the top-level field is overall_status; per-phase status fields (e.g. phases.tension_test.status) share the simpler name status because they live under their phase namespace. Read/write consistently.

Phase transition contract

overall_status MUST be advanced at each phase boundary. If a run pauses between phases, overall_status is what Resume mode reads to pick up at the right place. Leaving it stale corrupts Resume.

Each phase section below repeats its specific transition for in-context reference. This table is the authoritative contract.

At the start of every session:

1. Read naming-state.yaml.
2. Summarize: "Last session ended at phase [X]. Today we continue with [Y]."
3. Ask user: continue, re-run a specific phase, or skip forward.

After each meaningful exchange:

1. Update findings and phase status.
2. Bump last_updated.
3. Write the relevant phase file using the template from references/templates.md.
4. Save the state file. Do not auto-commit — the user decides when to commit naming-state.yaml and phase outputs.

Re-running a phase (invalidation rules)

When the user re-runs phase N, everything downstream is stale. Before executing, the skill MUST:

1. Mark phases.{N+1..}.status: pending and zero their counters.
2. Archive downstream files with version suffix. Scan for the highest existing .vN.md for that phase file and archive to .v(N+1).md (e.g. if 03-candidates.v1.md and 03-candidates.v2.md exist, archive current to 03-candidates.v3.md). Never silently overwrite.
3. Before archiving, only if the repo is git-tracked (git rev-parse --is-inside-work-tree succeeds), check git status for the file. If it has uncommitted changes, warn the user and ask whether to commit or discard before proceeding. In non-git projects, skip the git check and instead ask the user directly: "The current 0N-*.md will be archived as .v(N+1).md. Any unsaved edits? Confirm proceed."
4. Clear findings keys owned by downstream phases.
5. Announce to user: "Re-running Phase N will invalidate [list]. Proceed?"

Dirty state at decision time is a failure mode — not a feature.

GTM Skill Integration

After the state file is created, check for {repo}/docs/gtm/gtm-state.yaml. Do not trust file existence alone — check the state file for status: complete.

If gtm-state.yaml exists AND status: complete:

• Read all three relevant docs:
  • 01-brand-strategy.md → Mission, Values, Personality, Positioning
  • 02-market-landscape.md → ICP archetypes, competitors, JTBD
  • 03-messaging-framework.md → Voice, tone, content pillars
• Announce: "I see a completed GTM. I'll reuse personality, audience, voice, and competitor list. If anything's changed since GTM was written, tell me now."
• Skip Phase 1B (personality) and Phase 2 competitor discovery. Phase 2 still runs taxonomy classification + no-go zone analysis on the reused competitor list — those are naming-specific and GTM does not produce them.
• Set has_gtm_docs: true.

If gtm-state.yaml is missing, incomplete, or unreadable:

• Run full Phase 1 Brief and Phase 2 Namescape from scratch.
• Do NOT partially use individual GTM files — they may be stale.

Phase 0 (Rebrand only): Keep or Change Audit

Before any naming work, decide if renaming is actually the right move. Default answer is no — brand equity is expensive to rebuild.

Present these 4 triggers. Ask the user which apply:

1. Strategic drift — product or market has pivoted; current name is now misleading.
2. Legal risk — trademark conflict, can't expand to new class or geography, active dispute.
3. Systematic friction — name is unspellable, mispronounced, confused with a competitor, hard to search, or embarrassing to say.
4. Severe reputation damage — name itself has become a liability (rename alone rarely fixes this).

Decision rule:

• 0 triggers: Strongly recommend NOT renaming. Set overall_status: ended_no_change. Write summary to 01-brief.md. Skill ends cleanly.
• 1 trigger (not Strategic drift): Caution. Ask user to reconsider. If user insists on continuing, record in disputes and proceed.
• Strategic drift, OR 2+ triggers: Proceed to Phase 1. Advance state: overall_status: brief.

Record the triggers and decision in phases.rebrand_audit. On overall_status: ended_no_change, naming-state.yaml is preserved so the user can re-enter later by manually setting overall_status: brief.

Phase 1: Brief (Discovery)

One question at a time. Skip overlapping questions if GTM docs are loaded.

A. Benefit Ladder

Climb feature → functional → emotional → ultimate. This produces the creative springboard — 1-2 words the entire generation phase pivots on.

1. Feature: What does the product actually do? (mechanics)
2. Functional benefit: What problem does that solve?
3. Emotional benefit: How does the user feel after using it?
4. Ultimate benefit: What bigger identity or aspiration does that connect to?

Push once if the user stops at feature level:

"That's what it does. How does it make them feel after they use it — not in marketing words, in their own words?"

Example (project management tool):

• Feature: tasks + collaboration
• Functional: projects ship on time
• Emotional: in control, less chaos
• Ultimate: clarity — everything is handled

"Clarity" gives 100× more creative fuel than "project management."

B. Brand Personality (skip if GTM loaded)

• 4 personality axes (-5 to +5):
  • Funny ↔ Serious
  • Formal ↔ Casual
  • Respectful ↔ Irreverent
  • Enthusiastic ↔ Matter-of-fact
• 3–5 words describing the brand as a person
• Tone to avoid

C. Constraints

• Target markets (countries / languages)
• Domain requirement — must be .com? Or .io / .ai / .co acceptable?
• Syllable preference — 1–2 ideal, 3 acceptable, 4+ hard sell
• Naming conventions explicitly off-limits

D. Ultimate Benefit Concept

Distill to 1–2 words. Write into findings.ultimate_concept.

Output: 01-brief.md (see templates). Advance state: overall_status: namescape.

Phase 2: Namescape (Competitive Naming Map)

1. Competitor list:
   • If GTM loaded (has_gtm_docs: true): reuse competitor list from 02-market-landscape.md.
   • Otherwise: discover 20 competitors from scratch.
2. Classify each competitor name by taxonomy type (see references/taxonomy.md). This step runs regardless of GTM state — GTM does not produce taxonomy classifications.
3. Identify dominant patterns — which taxonomy types saturate? Which suffixes / prefixes / sound profiles recur?
4. Declare no-go zones — patterns so common you'd be invisible. This also runs regardless of GTM state.

If the user disagrees with a taxonomy classification, record in disputes and accept the user's classification. Agent taxonomy is advisory.

Output: 02-namescape.md. Advance state: overall_status: generate.

Phase 3: Multi-Model Candidate Generation

Divergent creativity benefits from model diversity. Different models have different priors for "good name."

Step 1: Detect available models

Run these availability probes, then (separately) auth probes:

# Codex CLI — availability
command -v codex && codex --version

# Antigravity CLI (agy) — availability. Serves the Gemini-family model
# for the `gemini` slot (see the note under models_available below).
command -v agy && agy --version

Availability check answers "is the binary installed and runnable?" If that passes, try a cheap authenticated smoke test (e.g. a trivial prompt with a 1-token max output, or the vendor's recommended auth-check command). If the smoke test fails, report the specific reason and instruct the user:

• codex: "codex installed but auth check failed — run codex login."
• agy: headless agy --print when not authenticated prints a Google authorization URL instead of answering. Smoke-test with a trivial prompt and treat empty output, or output that contains an authorization / sign-in URL (e.g. an accounts.google.com link), as a gate failure — it is an auth prompt, not a model answer. Instruct: "agy installed but not authenticated — run agy once interactively to sign in with Google." Both not-installed (probe above) and not-authenticated leave the slot unavailable.

Populate models_available.{claude,codex,gemini} based on the combined availability + auth result. Claude is always true. The gemini key names the model family — agy fills that slot with a Gemini-family model, so the key name is retained even though the CLI is now agy.

Step 2: Ask the user

I detected the following models: [list]. Pick generation ensemble:

• Claude only (~100 candidates) — fastest, lower diversity
• Claude + 1 other (~200 candidates) — recommended baseline
• All three (~300 candidates) — maximum diversity

You can also pick a custom model set.

Record in models_selected. Default candidates_per_model: 100 (user-tunable).

Step 3: Shared brief for all models

All selected models receive the same full brief. Diversity comes from model priors, not from forced taxonomy assignments. Each model generates candidates_per_model candidates across whichever taxonomy types it considers fit for the brief.

The brief (markdown). All placeholder paths are relative to naming-state.yaml — use the full dotted path when substituting.

Ultimate concept: {findings.ultimate_concept}
Personality axes: {findings.personality}
Target markets: {findings.constraints.markets}
Syllable preference: {findings.constraints.syllable_preference}
No-go patterns (skip these): {findings.no_go_patterns}
Taxonomy palette: see references/taxonomy.md (11 types)
Target count: {candidates_per_model}

Step 4: Invocation

Never let the brief reach the shell as unquoted, re-evaluated text. The brief contains free-form user input. Always write it to a file first with the Write tool, then feed the CLI from that file. Preferred: stdin heredoc or a --file flag. When a CLI supports neither and only takes the prompt as an argument (agy --print reads no stdin), embed the file with a double-quoted command substitution, written on its own line:

"$(cat brief.md)"

Double quoting is load-bearing: bash inserts the substituted file content literally and does not re-scan it, so any $(...), backticks, or ; in the brief stay inert (verified). Never use the unquoted form, and never eval the brief.

1. Generate a session timestamp: TS=$(date +%Y%m%dT%H%M%S).
2. Ensure the .raw/ directory exists before any writes: mkdir -p docs/naming/.raw. On first run the project may only have naming-state.yaml; without this step the brief write and CLI stdout redirect both fail with "No such file or directory".
3. Write the brief to docs/naming/.raw/brief-${TS}.md using the Write tool — not via shell echo/cat <<EOF. Use ${TS} throughout — the Write path MUST match the read paths in Step 4.
4. Invoke each selected external model, reading that file. Codex requires a git repository by default (OpenAI Codex non-interactive docs). In greenfield mode A (no code yet) or any non-git workspace, add --skip-git-repo-check. Detect: git rev-parse --is-inside-work-tree 2>/dev/null — falsy means add the flag.

# Detect git workspace once
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && CODEX_GIT_FLAG="" \
  || CODEX_GIT_FLAG="--skip-git-repo-check"

# Codex — read brief from file via stdin
codex exec $CODEX_GIT_FLAG - < docs/naming/.raw/brief-${TS}.md \
  > docs/naming/.raw/codex-${TS}.txt
CODEX_EXIT=$?

# Antigravity CLI (agy) — Gemini-family model. Print mode reads no stdin,
# so embed the brief in the prompt argument via double-quoted "$(cat ...)"
# (safe — see Step 4). Pin the Gemini model for family diversity vs Claude
# (main loop) and Codex (GPT-family). No --dangerously-skip-permissions:
# candidate generation is text-only and needs no tools, and the brief is
# user-controlled — auto-approving tool use would turn a prompt injection in
# the brief into real file/command execution. Headless --print with default
# permissions still answers (verified); if the model ever tries a tool it
# stalls until --print-timeout and degrades, which is the safe outcome.
# --print-timeout explicit (matches the default) so a stalled model can't
# block generation indefinitely — don't rely on an implicit default.
agy --model "Gemini 3.1 Pro (High)" --print-timeout 5m --print \
  "Generate the target number of brand-name candidates from the brief below.
Output one candidate per line, no numbering or commentary.

$(cat docs/naming/.raw/brief-${TS}.md)" \
  > docs/naming/.raw/gemini-${TS}.txt
GEMINI_EXIT=$?

Claude (the skill executor) generates in-session against the same brief.

Step 5: Guard each external invocation

External CLIs fail for many reasons (rate limit, auth expiry, network, model outage). Never silently proceed on failure. After each invocation, in this order:

1. Check exit code. Non-zero → failure. Then two content checks on the raw output file — either one is a failure and degrades the slot the same way (drop it, run Claude + Codex only):
   • Empty output: agy's --print has a known non-TTY stdout-drop issue (exit 0 but blank output), so a zero-length gemini-${TS}.txt means the branch produced nothing. [ -s file ] catches it.
   • Auth prompt, not an answer: an auth lapse between the Step 1 gate and this call makes agy print a Google authorization / sign-in URL (e.g. an accounts.google.com link) into the file. That output is non-empty, so it slips past [ -s ] and would be parsed as candidate names. Reuse the Step 1 auth-URL match here: if the raw output contains such a URL, treat the branch as failed, not as candidates.
2. Parse the output into a candidate list first, then count. Models may emit one-per-line, numbered lists, bullets, wrapped paragraphs, or comma-separated — count the parsed candidates, not raw wc -l. The brief instructs models to output one candidate per line (see Step 3 brief template), but tolerate the common alternatives: strip bullets/numbering, split on commas inside a wrapped paragraph, merge multi-line bullets. Require at least candidates_per_model * 0.5 parsed candidates (e.g., 100 requested → 50 minimum, 30 requested → 15 minimum). Fewer than that → truncation or error response.
3. On failure: (a) downgrade models_selected by removing the failed model; (b) notify the user explicitly with the reason; (c) ask whether to retry, drop the model, or abort Phase 3. Do not merge the failed model's output into 03-candidates.md.

Step 6: Merge + dedupe

Claude reads all successful outputs and dedupes. Dedupe rules:

Apply in order — first rule that matches wins:

1. Case-insensitive exact match → drop duplicate.
2. Names < 5 characters → exact match only. Different spellings are kept (short names legitimately diverge at low edit distance).
3. Names = 5 characters, Levenshtein distance = 1 → drop duplicate (preserve the one with clearer etymology or lower taxonomy saturation).
4. Names = 5 characters, Levenshtein distance = 2 → borderline: keep both and flag in 04-evaluation.md for human review.
5. Names ≥ 6 characters, Levenshtein distance ≤ 2 → drop duplicate (same preservation rule as #3).
6. Phonetically near-identical spellings regardless of Levenshtein (e.g., Kava / Cava, Klair / Clare) → borderline: keep both and flag.

Write 03-candidates.md grouped by taxonomy type. Each entry records its source model so later analysis can see which model tends to win.

Generation Discipline

During generation, do not self-judge. LLM-failure-mode penalties (generic suffixes, stitched portmanteaus, etc.) are applied in Phase 4 Gate — not here. This preserves the approximate-thinking zone.

Use these angles when generating:

1. Synonyms of ultimate benefit.
2. Latin / Greek roots (etymonline.com).
3. Adjacent fields (e.g. "clarity" → optics, water, weather, music).
4. Sound patterns (K/T/P strong; L/M/S soft; V daring).
5. Metaphors and physical objects.

Output: 03-candidates.md. Advance state: overall_status: evaluate.

Phase 4: Two-Layer Evaluation