wiki-migrate

name	Wiki Migrate
description	One-shot conversion from legacy `.crewly/knowledge/*.json` + loose `.md` + agent `memory.json` into the v2.1 three-scope vault structure. Default dry-run; idempotent; never deletes legacy files.
version	1.0.0
category	knowledge
skillType	claude-skill
assignableRoles	["orchestrator","team-leader"]

Wiki Migrate

For users who installed Crewly BEFORE the v2.1 LLM-wiki landed (2026-05-22+). The legacy knowledge stores live at:

Legacy source	New target
<project>/.crewly/knowledge/decisions.json[]	<project>/.crewly/wiki/llm-curated/decisions/<date>-<slug>.md
<project>/.crewly/knowledge/patterns.json[]	<project>/.crewly/wiki/llm-curated/patterns/<date>-<slug>.md
<project>/.crewly/knowledge/gotchas.json[]	<project>/.crewly/wiki/llm-curated/patterns/<date>-<slug>.md
<project>/.crewly/knowledge/relationships.json[]	<project>/.crewly/wiki/llm-curated/people/<date>-<slug>.md
<project>/.crewly/knowledge/learnings.md	appended to <project>/.crewly/wiki/llm-curated/log.md
<project>/.crewly/knowledge/*.md (loose)	<project>/.crewly/wiki/llm-curated/decisions/<slug>.md
<project>/.crewly/docs/*.md ← legacy query-knowledge storage	<project>/.crewly/wiki/llm-curated/docs/<slug>.md
<project>/CLAUDE.md / AGENTS.md / DEPLOYMENT*.md	<project>/.crewly/wiki/llm-curated/runbooks/<slug>.md
<project>/deploy/*.md, <project>/docs/deploy*.md, <project>/.claude/commands/deploy*.md	<project>/.crewly/wiki/llm-curated/runbooks/<slug>.md
~/.crewly/agents/<id>/memory.json roleKnowledge[]	<project>/.crewly/wiki/llm-curated/{patterns,decisions}/<date>-<slug>.md (copy; original retained)
<crewly-src>/config/sops/<role>/*.md (OSS-distributed)	~/.crewly/global-wiki/llm-curated/sops/<role>/<slug>.md (via migrate/oss-sops)
<crewly-src>/config/domain-sops/*.sop.md	~/.crewly/global-wiki/llm-curated/sops/domain/<slug>.md
<crewly-src>/config/templates/pro-sops/norms/*.md	~/.crewly/global-wiki/llm-curated/sops/pro-norms/<slug>.md

Per spec §6 the agent's memory.json stays put — this skill copies its roleKnowledge entries to the wiki rather than moving them, so private agent memory keeps working unchanged.

What the legacy stores were (and what replaces them)

The migration fully retires the legacy query-knowledge skill (2026-05-27). After migration:

• <project>/.crewly/docs/*.md → still on disk (NOT deleted) but no agent skill reads them; all content is in the wiki
• <project>/.crewly/knowledge/* → same — preserved as source of truth but consumers now use wiki-query
• The single replacement skill is wiki-query (v2.1) — same query verb, richer vault routing (global / team / project)

If you're updating prompts that referenced query-knowledge, swap to:

bash {{AGENT_SKILLS_PATH}}/core/wiki-query/execute.sh --vault <vault-path> --query "<topic>" --top-k 5

Vault picker:

• Org-wide SOPs / cross-team decisions / OKR → ~/.crewly/global-wiki
• Team SOPs / team norms → ~/.crewly/teams/<team-uuid>/wiki
• Project decisions / customers / project runbooks → <project-root>/.crewly/wiki

Guarantees

• Default dry-run. No writes happen unless --apply (or confirm: true in JSON body) is passed.
• Idempotent. A manifest at <vault>/.migration-state.json records every migrated entry's content hash + sourceId. Re-runs skip duplicates.
• Legacy preserved. .crewly/knowledge/ and memory.json files are NEVER deleted. Rollback is just "ignore the new vault."
• Bootstrap on apply. If the project / global / team vaults are missing SCHEMA.md, they're created with the v2.1 skeleton before any content lands.
• Routing default. Everything goes to the project vault. Items whose body looks cross-project (mention foreign team UUIDs, "company-wide", OKR lingo, cross-project codenames) are tagged routing_uncertain: true in frontmatter; wiki-lint surfaces them later for human review / promotion to global.

Inputs

Flag	Required	Default	Description
--project-root <abs path>	yes	—	The dir containing .crewly/.
--apply	no	off	Execute writes. Without this, run a dry-run scan.
--no-memory	no	off	Skip the per-agent memory.json import.

What you do with the report

On scan (dry-run):

• Read proposedPages — each row tells you target path, source file, sourceId.
• Look at bootstrapNeeded — confirms which vaults will be created.
• Look at summary — counts per source type.
• Look for routingUncertain: true rows — these will land in the project vault but flagged for later human review.

On apply:

• Confirm applied count matches the proposal.
• bootstrapped lists the vault dirs newly created.
• manifestPath is the persistent ledger — cat it to audit the migration.
• Run wiki-lint --vault <project-vault> afterwards to surface any routing_uncertain items.

Examples

Dry-run:

bash execute.sh --project-root /Users/me/code/myproject

Apply for real:

bash execute.sh --project-root /Users/me/code/myproject --apply

Apply but skip agent memory.json copies:

bash execute.sh --project-root /Users/me/code/myproject --no-memory --apply

Failure modes

• 400 invalid_input — projectRoot is not absolute, or confirm was missing on apply (skill handles this automatically).
• 404 project_root_missing — the directory doesn't exist.