import-context

/import-context — Adopt Prior AI Footprint into HQ

Hydrate a fresh HQ install from the user's existing AI footprint. Two complementary sources:

1. Artifacts on disk — skills, hooks, policies, MCP configs, CLAUDE.md files, knowledge-bearing repos, claude-bearing repos, and prior /prd outputs.
2. Conversation history — Claude Code sessions, Codex sessions, Grok sessions, and (via export) claude.ai chat threads. Sub-agents mine sampled threads and propose HQ context to bootstrap company setup: candidate companies, knowledge seeds, policies, and projects. Everything is a proposal — nothing lands without an explicit accept.

Discovers artifacts, infers work ontology from prior plans and conversations, and guides a per-category import — creating missing companies and synthesizing workers on demand.

/import-claude is the former name and remains a deprecated alias that routes here.

Ships via the hq-core release pipeline. Core changes are made in the hq-core staging repo and reach the public indigoai-us/hq-core release through promotion.

Preflight

Before any scan, verify all gates. Each is a hard stop.

1. Plan-Mode Guard

If the session is in Plan Mode (active instructions restrict edits to a single ~/.claude/plans/*.md file), STOP and print verbatim:

/import-context writes to workspace/imports/, companies/, and core/workers/ — paths Plan Mode forbids. Exit plan mode (Shift+Tab) and re-run, or review the approved plan at ~/.claude/plans/ first.

Do not degrade. Do not redirect writes. Exit the skill.

2. HQ Root + Setup Check

• HQ_ROOT="$(pwd)" (or resolve from settings). Confirm .claude/ and companies/manifest.yaml exist.
• If manifest.yaml is missing: print /import-context requires /setup to have been run first — run /setup and retry. and exit.

3. Self-Protection (Scope Sanity)

For every --scope=<dir> flag (and for the default allowlist), resolve with realpath. Abort if any resolves to a path that starts with $HQ_ROOT — the scanner refuses to re-import HQ into itself.

4. Active-Run Guard

Read workspace/orchestrator/active-runs.json when it exists. If it is missing, treat the repo as unclaimed. If the current repo is claimed by another run, refuse. /import-context writes to registries — it cannot share the repo.

Flags

Parse $ARGUMENTS:

Flag	Effect
--dry-run	Scan + ontology inference + report; no imports, no manifest writes, no worker.yaml creation
--scope=<dir>	Add a custom parent dir to scan (repeatable; additive to default allowlist)
--ontology-only	Scan + ontology inference; skip every artifact triage
--cluster-min-skills=<N>	Minimum skills in a cluster to trigger worker-synthesis prompt (default: 2)
--claude-export=<path>	Path to a claude.ai data export (unzipped dir or conversations.json) so claude.ai chat threads join conversation mining
--no-conversations	Skip conversation mining (Phase 3.5) entirely
--conversations-only	Scan + conversation mining + proposal triage; skip ontology and artifact triage

Phase 1: Scan

Announce: Scanning for Claude artifacts… this is read-only and takes ~5s on the default allowlist.

SCAN_ID="$(date -u +%Y%m%dT%H%M%SZ)"
SCAN_DIR="workspace/imports/${SCAN_ID}"
mkdir -p "$SCAN_DIR"

bash .claude/skills/import-context/scan.sh \
  --hq-root="$HQ_ROOT" \
  --output="$SCAN_DIR/report.json" \
  ${CLAUDE_EXPORT:+--claude-export="$CLAUDE_EXPORT"} \
  ${SCOPE_FLAGS[@]/#/--scope=}

Confirm report.json parses as JSON (jq -e '.categories' "$SCAN_DIR/report.json" >/dev/null). If not, surface the scanner's stderr and abort.

Check discovery status (jq -r '.discovery.ok' "$SCAN_DIR/report.json"). The scanner records whether discovery actually completed, so a failed scan is never mistaken for an empty one. If .discovery.ok is false, do not treat any zero counts as authoritative — surface the failure loudly, e.g.:

⚠️  Discovery did not complete — the counts below may be UNDER-reported.
The scanner could not read part of the scope (see .discovery.errors in the report).
This is "could not look", not "nothing to import". Fix the access issue (or
re-run with a narrower --scope) before concluding there is nothing to migrate.

Print the contents of .discovery.errors and let the user decide whether to continue, rather than silently reporting zeros.

Redact the report before anything touches user-visible surfaces:

bash .claude/skills/import-context/redact.sh --json-fields "$SCAN_DIR/report.json" > "$SCAN_DIR/report.redacted.json"
mv "$SCAN_DIR/report.redacted.json" "$SCAN_DIR/report.json"

Phase 2: Overview

Read $SCAN_DIR/report.json. Print a counts-per-category summary:

Scan complete. Found:
  plans               {N}
  mcp_servers         {N}
  settings_fragments  {N}
  commands            {N}
  skills              {N}
  hooks               {N}
  policies            {N}
  claude_md           {N}
  claude_repos        {N; {K} marked is_knowledge}
  agents              {N}
  conversations       {N stores: claude-code {a} sessions · codex {b} · grok {c} · claude.ai {d or "no export"}}

Report: workspace/imports/{scan_id}/report.json

If all counts are zero and .discovery.ok is true: No Claude artifacts found in scanned scope. Exiting. Stop. (If .discovery.ok is false, do not print this — discovery failed; surface the errors per the discovery-status check above instead of claiming nothing was found.)

If --dry-run: print Dry-run complete. No imports performed. and exit.

AskUserQuestion — one call, one item:

• question: "How would you like to proceed?"
• header: "Import flow"
• multiSelect: false
• options:
  • Ontology first — "Infer companies from prior plans, then mine conversations, then triage artifacts"
  • Artifacts first — "Skip ontology and conversation mining, go straight to per-category triage"
  • Review report — "Open report.json in your editor first, then decide"
  • Exit — "Write the report and stop"

On Review report: open -e "$SCAN_DIR/report.json" and re-ask after user continues. On Exit: print report path and stop.

Phase 3: Ontology Inference

Skip if --conversations-only, or if user chose Artifacts first and --ontology-only is NOT set.

Build the corpus:

PLANS_COUNT=$(jq '.categories.plans | length' "$SCAN_DIR/report.json")

If PLANS_COUNT == 0: print No plan files found — skipping ontology inference. and continue to Phase 4.

Otherwise, spawn a Task sub-agent:

• Prompt: contents of .claude/skills/import-context/ontology.md (verbatim) followed by the appended inputs:
  1. Plan index — all plan filenames + first-line headings from the report
  2. Plan corpus — for ≤50 most-recent plans, read the first 200 lines each, pipe through redact.sh, and embed
  3. Existing HQ companies — the top-level slug list from companies/manifest.yaml
  4. Scan context — the counts block from Phase 2

Cap the corpus at 50 plans. For older plans include filename only (as the ontology template instructs).

Write the sub-agent response verbatim to $SCAN_DIR/ontology.md.

Parse ## Inferred Companies table. For each row:

1. Skip if slug already exists in companies/manifest.yaml.

2. AskUserQuestion (one per row):

   • question: "Create HQ company {slug}? ({signal_strength} signal — {rationale})"
   • header: "Ontology"
   • options:
     • Create {slug} — "Runs /newcompany {slug} and seeds core/knowledge/context.md"
     • Adjust slug — "Rename before creating" (follow-up free-text prompt)
     • Defer — "Skip for now; revisit later"
     • Reject — "Don't create; ontology call was wrong"

3. On Create: inline-invoke /newcompany {slug} via Skill tool. On return, write the row's suggested knowledge seed to companies/{slug}/knowledge/context.md (seed a fresh file; prepend frontmatter per knowledge-ontology spec).

Routing safety. /newcompany is the enforcer that scaffolds all company content under companies/{slug}/ — import-context delegates company/worker creation to it rather than writing those paths itself. Do not hand-place imported policies, workers, or knowledge into core/; company-scoped artifacts belong under the created companies/{slug}/ tree (see core/policies/hq-customizations-live-in-personal-or-company.md and hq-company-scoped-writes-verify-company.md).

If user chose --ontology-only: after this phase, print summary and exit with report + ontology locations.

Phase 3.5: Conversation Mining

Skip if --no-conversations, if the user chose Artifacts first, or if categories.conversations is empty. This phase mines the user's prior AI conversations — across every runtime, not just Claude Code — and turns them into proposals for HQ context. It exists to bootstrap company setup: a user with months of Claude/Codex/Grok history should not start HQ from a blank slate.

Sources

The scanner reports conversation stores as store-level entries (session counts + paths — transcripts are never bulk-loaded into the parent session):

source	location	contents
claude-code	~/.claude/projects/{project}/*.jsonl	Claude Code session transcripts, grouped by working directory
codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	Codex CLI session rollouts
grok	~/.grok/sessions/{encoded-cwd}/{session-id}/updates.jsonl	Grok CLI session transcripts, grouped by working directory
claude-ai	--claude-export=<path> (conversations.json from a claude.ai data export)	claude.ai chat threads — web, desktop, and mobile

claude.ai chats have no on-disk store. If --claude-export was not supplied, tell the user once how to get one (claude.ai → Settings → Privacy → Export data; the email link contains conversations.json) and offer to continue without it. Never scrape a browser session or claude.ai cookies to obtain chat history.

Gate (AskUserQuestion, one call)

• question: "Mine your conversation history for proposed HQ context? Found: {a} Claude Code sessions, {b} Codex, {c} Grok{, claude.ai export with {d} chats}. Threads are read locally, sampled, and redacted — you approve every proposal before anything is created."
• header: "Conversations"
• options:
  • Mine all sources — "Sample recent threads from every store"
  • Pick sources — "Choose which stores to mine" (follow-up AskUserQuestion, multiSelect: true, one option per store)
  • Skip — "No conversation mining"

Mining (one Task sub-agent per source; parent stays text-only)

For each accepted source, spawn a Task sub-agent whose prompt is the contents of .claude/skills/import-context/conversations.md (verbatim) followed by:

1. Session index — paths + mtimes for that store, most-recent first (from the scan report).
2. Sampling budget — mine at most the 40 most-recent sessions; per session read only enough to understand what the work was about (first user message, closing assistant summary, plan/decision-shaped chunks); hard cap ~200 lines per session; pipe every excerpt through .claude/skills/import-context/redact.sh before it enters the sub-agent's notes.
3. Existing HQ state — company slugs from companies/manifest.yaml, plus existing knowledge/policy/project titles for those companies (filenames only), so proposals extend rather than duplicate.

Write each sub-agent's response verbatim to $SCAN_DIR/conversations-{source}.md. Sub-agents return proposals only — never raw transcript bulk.

Proposal triage

Merge the ## Proposals tables from every source report; dedupe on (type, company, title). Present via AskUserQuestion in batches of ≤4, one call per batch:

• question: "{type} → {company}: {title} — {one-line evidence}"
• header: "Proposal"
• options:
  • Accept — "Create it now"
  • Edit first — "Adjust title/company/content before creating" (follow-up free-text)
  • Defer — "Keep in the report for later"
  • Reject — "Wrong call — drop it"

On Accept, route by type — never hand-place company content outside its tenant:

type	action
company	inline-invoke /newcompany {slug}, then seed companies/{slug}/knowledge/context.md from the proposal's knowledge seed
knowledge	write the proposal's draft to companies/{co}/knowledge/{slug}.md (frontmatter per knowledge spec)
policy	validate frontmatter against core/knowledge/public/hq-core/policies-spec.md; write to companies/{co}/policies/{slug}.md — company scope only, never core/policies/
project	create companies/{co}/projects/{name}/README.md seeded with the proposal summary and open threads; recommend /prd to grow it into a PRD — never fabricate a prd.json from thread inference
worker	feed into Phase 6 cluster detection as a proposed cluster

Record every decision in $SCAN_DIR/conversation-proposals.json and add accepted proposals to workspace/imports/index.json keyed by sha256 of (source, type, company, title) — re-runs skip already-triaged proposals silently.

Privacy rules (hard)

• Transcripts never leave the machine and are never bulk-embedded in the parent session — sub-agents sample locally and return proposals only.
• Every excerpt shown to the user or persisted under $SCAN_DIR passes through redact.sh first.
• Tenant hygiene: each proposal targets exactly one company. If a thread spans companies, split it into per-company proposals; if the company is unclear, mark it unknown and let the triage prompt resolve it. Never merge two companies' facts into one knowledge file.
• --dry-run exits at Phase 2 as usual — no mining runs.

Phase 4: Per-Category Triage

Skip if --conversations-only (jump to Phase 7 after conversation mining).

Order (empties skipped): mcp_servers → settings_fragments → commands → skills → hooks → policies → agents → claude_md → claude_repos. For knowledge handling, use only repo entries with claude_repos[].is_knowledge == true.

Plans are intentionally excluded — they stay at ~/.claude/plans/.

For each non-empty category:

AskUserQuestion — category-level gate:

• question: "{N} {category} found. How to proceed?"
• header: category name
• options:
  • Review each — "Decide per item"
  • Import all safe — "Auto-import items with no conflicts + no redactions"
  • Skip category — "Leave these untouched"

Review each

Batch items in groups of 5. For each batch, one AskUserQuestion with 5 items (one per artifact), multiSelect: false:

• question: "{source_path} — {suggested_destination}"
• header: artifact name (basename)
• options:
  • Keep — "Import to suggested destination"
  • Merge — "Merge with existing file at destination (will show diff)" (only if conflict.exists && !hash_match)
  • Rename — "Keep both (adds .imported-{scan_id} suffix)" (only if conflict)
  • Skip — "Don't import this item"
  • Assign to company — "Scope to a company not yet guessed"

On Assign to company: follow-up with company picker (options = current manifest slugs + New company…). On New company… with a provided slug: inline-invoke /newcompany {slug} before continuing.

On Merge: show unified diff via diff -u source dest and ask overwrite / keep-both / skip.

Redaction confirm — if the item has non-empty redacted_fields, before importing ask:

• question: "{filename} contains {N} credential pattern(s). Import redacted?"
• options:
  • Import redacted — "Replace with <REDACTED:*> tokens"
  • Skip file — "Don't import at all"
  • Include raw — "Copy verbatim with credentials (only if you know what you're doing)"

Import all safe

Auto-import items where conflict.exists == false AND redacted_fields == []. Everything else falls through to the Review loop.

Import step (per item)

After every per-item decision resolves to Keep/Merge/Rename:

1. Run redactor on source: bash .claude/skills/import-context/redact.sh "$source" > "$tmp"
2. Copy $tmp → resolved destination (respecting Rename suffix)
3. Update workspace/imports/index.json with {sha256: {destination, scan_id, timestamp}} — idempotency store

Phase 5: Registration (per-category, after its batch completes)

Update registries immediately after each category finishes — limits blast radius if a later phase fails.

Category	Registration step
mcp_servers	Merge into .claude/settings.json#mcpServers via structured jq write
settings_fragments	Field-level merge into .claude/settings.json (never replace file)
commands	File-presence only
skills	Copy to .claude/skills/{name}/; if worker.yaml sibling exists → route to worker synthesis (Phase 6)
hooks	Copy to .claude/hooks/; add matcher to settings.json#hooks[]; verify hook-gate.sh --list shows it
policies	Validate frontmatter against core/knowledge/public/hq-core/policies-spec.md; place in companies/{co}/policies/ when a company is bound, otherwise personal/policies/. Never write imported policies to core/policies/.
agents	Copy to .claude/agents/
claude_md	Merge into nearest-root CLAUDE.md (show diff, confirm before write)
claude_repos	Per-repo prompt: Symlink / Move / Skip; update manifest.yaml company repos: array on adoption. When is_knowledge is true, materialize its knowledge/ content in a real canonical knowledge directory and register it in the relevant company knowledge tree. Company knowledge always stays a plain vault-synced directory; only personal knowledge may use embedded Git for separate history.

No null fields — every manifest.yaml company entry and every worker.yaml must include all required fields from the schema. If a field is unknown, ask before writing. (core/workers/registry.yaml is auto-generated — no direct writes.)

Phase 6: Worker Synthesis

Runs after skills + claude_repos triage completes. Entries with claude_repos[].is_knowledge == true supply knowledge content. Reads imported items from index.json.

Cluster detection

A cluster is any group of imported artifacts where:

• ≥--cluster-min-skills skills share a domain keyword (filename stem, SKILL.md description first word, or parent dir basename), OR
• ≥1 skill + ≥1 claude_repos entry with is_knowledge == true from the same source repo/parent, OR
• ≥1 agents/*.md file with both tool list + instructions (worker-shaped)

Per-cluster prompt

For each detected cluster, AskUserQuestion:

• question: "Cluster {keyword}: {N} skills + {M} knowledge repos. Synthesize as a worker?"
• header: "Worker synthesis"
• options:
  • Create worker — "Inline /newworker with skills + knowledge pre-filled"
  • Keep loose — "Leave as individual skills/knowledge"
  • Split cluster — "I'll pick which items belong to the worker"
  • Skip — "Ignore this cluster"

On Create worker

Registration order is strict — violate this and the worker's knowledge pointers won't resolve:

1. Verify imported company knowledge lives in a plain real directory (test -d and ! test -L). The manifest knowledge value is the directory path; it does not identify a repository.
2. Inline-invoke /newworker with pre-filled fields:
   • name: inferred from dominant keyword
   • scope: company-scoped if cluster maps to a known slug, else core/workers/public/
   • skills: paths of imported skill dirs
   • knowledge: paths of imported knowledge dirs (must already be registered)
   • description: synthesized from SKILL.md frontmatter (user edits in the /newworker flow)
3. /newworker writes worker.yaml; core/workers/registry.yaml regenerates automatically via reindex. Company knowledge files remain plain vault-synced files and are not committed to an embedded repository.
4. Record the cluster in $SCAN_DIR/synthesized-workers.json.

Shared vs company default

If the cluster has no clear company anchor and the user picks Create worker without specifying scope: default to loose skills (do not auto-promote to core/workers/public/). Synthesis into shared scope requires explicit accept. This is the conservative default per the approved plan's unresolved-question #5.

Phase 7: Reindex & Summary

After all phases finish:

qmd update 2>/dev/null || true

Write $SCAN_DIR/summary.md:

# Import Summary — {scan_id}

## Companies
- Created: {slugs or "none"}
- Seeded from ontology: {slugs or "none"}

## Conversation Mining
| source | sessions sampled | proposals | accepted | deferred |
|---|---|---|---|---|
| ... | | | | |

## Imports (by category)
| category | imported | skipped | conflicts |
|---|---|---|---|
| ... | | | |

## Workers Synthesized
{table: name | scope | skills | knowledge}

## Repos Adopted
{table: source | destination | mode (symlink/move)}

## Credentials Redacted
{count per pattern name}

## Next Steps
- Run `/cleanup --audit` to validate no broken state
- Review `workspace/imports/{scan_id}/ontology.md` for deferred ontology rows
- Review `workspace/imports/{scan_id}/report.json` for skipped items

Print the summary path + git status diff preview (not commit — user commits).

AskUserQuestion — post-run:

• options:
  • Run /cleanup --audit — "Validate nothing landed broken"
  • Run /learn — "Capture insights from this import"
  • Commit now — "Stage and commit eligible HQ or repo changes; company knowledge syncs through the company vault"
  • End — "Done for now"

Rules

• Plan Mode refuse — Preflight halts before any scan. No silent degrade.
• Self-exclusion — Preflight step 3 resolves scope paths and $HQ_ROOT with realpath and aborts when a scope resolves inside $HQ_ROOT; scan.sh also excludes $HQ_ROOT during discovery.
• Read-only scan — scan.sh never writes outside $SCAN_DIR. Confirmed by scan.sh's lack of any write paths other than --output.
• Redact before display — every preview/prompt/report.json the user sees has been through redact.sh. Raw source file content is never shown verbatim without explicit Include raw choice.
• Idempotent — re-runs check workspace/imports/index.json by sha256 and skip already-imported items silently. Different destination for same source → surface as duplicate source.
• Conflict decision required — conflict.exists && !hash_match cannot be auto-resolved. User picks.
• AskUserQuestion only — every user-facing choice goes through AskUserQuestion. Never markdown numbered lists.
• Inline scaffolding — unknown company slugs invoke /newcompany inline; worker clusters invoke /newworker inline. No deferred "you should run X later" hand-waves.
• Registry completeness — every write to manifest.yaml and every new worker.yaml fills all required schema fields. No nulls. If a field is unknown, ask. core/workers/registry.yaml is a generated artifact — never written directly.
• Generic-user safety — report.json and summary.md substitute literal $HOME for $HOME/ prefixes. Scanner's sub_home() enforces this.
• Plans are never imported — they stay at ~/.claude/plans/. Only feed ontology inference.
• Conversations are never imported — session stores stay where they are (~/.claude/projects/, ~/.codex/sessions/, ~/.grok/, the export file). Mining reads samples and produces proposals; only accepted proposals materialize as HQ files.
• Proposals, not conclusions — conversation mining output is always a proposal gated by AskUserQuestion. Low-signal inferences are marked as such; the user is the authority on what their history means.
• Per-repo prompt — every claude-bearing repo gets its own prompt. No batch-adopt.
• Registration-order discipline (worker synthesis) — knowledge before worker.yaml. Always.
• No execution — this command mutates HQ structure only. It does not run imported skills, execute worker tasks, or invoke any other work.
• Checkpoint after write — if any Phase 5 registration succeeds, the Auto-Checkpoint PostToolUse hook fires. Do not race it.

Files this skill touches

Reads: companies/manifest.yaml, core/workers/registry.yaml, workspace/imports/index.json, user's disk (per scope), conversation stores read-only (~/.claude/projects/, ~/.codex/sessions/, ~/.grok/, --claude-export path).

Writes: workspace/imports/{scan_id}/ (report, ontology, conversations-{source}, conversation-proposals, summary, synthesized-workers), workspace/imports/index.json, .claude/{commands,skills,hooks,policies,agents}/, .claude/settings.json, plain company directories under companies/{co}/{knowledge,policies,projects,repos,workers}/, companies/manifest.yaml (with knowledge as a plain directory path), core/workers/public/{id}/worker.yaml (registry auto-regenerates), CLAUDE.md (on user confirm).

Never touches: ~/.claude/plans/ (read-only for ontology), conversation stores (read-only for mining), ~/.ssh/, ~/.aws/, ~/.gnupg/, .env, any shell rc file (per HQ deny lists).

See also

• Scanner: .claude/skills/import-context/scan.sh
• Streaming scan events for apps (scan.sh --progress-json, relayed by hq import scan --json --stream): .claude/skills/import-context/progress-json.md. This skill does not use the flag; Phase 1 runs the scanner as shown above.
• Redactor: .claude/skills/import-context/redact.sh
• Ontology prompt: .claude/skills/import-context/ontology.md
• Conversation-mining prompt: .claude/skills/import-context/conversations.md
• Deprecated alias: .claude/skills/import-claude/ (stub routing here)
• Plan file (archive): ~/.claude/plans/<plan-name>.md