do-wiki-align

You are a senior engineer and wiki maintainer retrofitting an existing wiki-like markdown corpus to this repo's Obsidian-friendly conventions.

This skill is broader than /do-wiki-lint.

• Use /do-wiki-lint for ongoing maintenance of a wiki that already largely follows the conventions.
• Use /do-wiki-align when the structure, naming, link style, hub notes, or note graph need normalization or retrofit work.

The target output is:

• an Obsidian-friendly note graph
• durable category notes with canonical kebab-case filenames
• internal links written as [[kebab-case-note-name]]
• index.md functioning as the single root hub, with a concise ## Overview section near the top
• stronger reciprocal links and fewer isolated notes
• an explicit SCHEMA.md when one is missing or materially incomplete
• lean operational AGENTS.md / CLAUDE.md files that point into the wiki for durable deep reference instead of duplicating long, fast-aging technical knowledge

Input

The alignment target is: $ARGUMENTS

If no explicit target is provided, align the most plausible wiki-like root in the current workspace.

Step 0 — Parse arguments

$ARGUMENTS may contain an optional mode flag and an optional target scope.

Examples:

• --guidance-only
• --guidance-only apps/api
• wiki
• apps/web

Parse the arguments like this:

1. If --guidance-only appears anywhere, set the mode to guidance-only.
2. Remove the flag from the remaining text.
3. Treat the remaining text, if any, as the target root or scope.
4. If no target remains, use the most plausible wiki root and its most relevant guidance scope.

Guidance-only mode

In --guidance-only mode:

• inspect and update only relevant AGENTS.md and CLAUDE.md files
• read the wiki so those guidance files can point to the right hub notes and durable pages
• treat the wiki as read-only context only
• do not rename or move wiki notes
• do not normalize links across the whole wiki corpus
• do not restructure category directories
• do not create, update, or append any wiki file, including SCHEMA.md, index.md, log.md, or any legacy root overview.md

Phase 1 — Resolve the wiki-like root and guidance scope

Locate the most plausible wiki-like root by checking for signals such as:

• SCHEMA.md
• index.md
• overview.md as a legacy root-hub signal
• log.md
• dense markdown trees under directories like wiki/, knowledge/, vault/, notes/, docs/, or research/
• existing source, topic, concept, entity, or analysis note clusters

Rules:

1. If the user names a root or scope explicitly, prefer it.
2. If multiple roots are plausible, ask the smallest follow-up question needed.
3. If nothing wiki-like exists yet, stop and recommend:

/do-wiki-build <topic or wiki goal>

Treat the chosen location as <wiki root> for the rest of this skill.

Then resolve the relevant guidance-file scope.

Guidance files may exist at multiple levels in a monorepo. Do not assume there is only one global pair.

Use these scoping rules:

1. Always inspect root-level AGENTS.md / CLAUDE.md when they exist.
2. Always inspect <wiki root>/AGENTS.md / <wiki root>/CLAUDE.md when they exist.
3. If the target names a subtree such as an app, package, service, or module, inspect the nearest relevant scoped guidance files in or above that subtree.
4. If no explicit subtree is named, inspect additional scoped guidance files only when the wiki scope clearly covers them or when they likely contain duplicated or stale deep-reference material that should point into the wiki.
5. Treat mirror files such as CLAUDE.md files that only defer to AGENTS.md as mirrors. Keep them thin unless the workspace clearly intends otherwise.

Phase 2 — Inspect the current shape

Before proposing changes, read:

1. ${CLAUDE_SKILL_DIR}/references/alignment-rules.md
2. ${CLAUDE_SKILL_DIR}/references/proposal-template.md
3. ${CLAUDE_SKILL_DIR}/references/guidance-file-triage.md
4. <wiki root>/SCHEMA.md when it exists
5. <wiki root>/index.md when it exists
6. <wiki root>/overview.md when it exists, so you can assess whether it contains legacy root-hub content that should be folded into index.md
7. <wiki root>/log.md when it exists
8. the relevant AGENTS.md / CLAUDE.md files for the resolved scope
9. a representative sample of notes from the target scope

In --guidance-only mode, only read the minimum wiki context needed to point guidance files at the right hub or scoped notes. Do not perform a full graph audit.

Map the current state:

• current directory structure
• current filename patterns
• current internal link styles such as [[wikilinks]], markdown links, plain-text references, or mixed styles
• existing hub notes and whether they are effective
• obvious duplicate note identities
• broken or unresolved internal links
• missing reciprocal backlinks where relationships are material
• notes that should likely move into topics/, entities/, concepts/, or analyses/
• existing sources/ directories whose pages should be absorbed into topic/entity/concept pages
• relevant AGENTS.md / CLAUDE.md files and whether each is canonical, scoped, or mirror-only
• stale or duplicated deep-reference sections in guidance files that should instead point into the wiki
• guidance sections that should stay local and operational, such as commands, hard rules, safety constraints, scope boundaries, and canonical source-of-truth pointers

Treat the existing corpus with care. The goal is alignment, not a destructive rewrite.

Phase 3 — Build the proposal and stop

Do not change any files yet.

Use ${CLAUDE_SKILL_DIR}/references/proposal-template.md as the exact structure for your proposal.

The proposal should distinguish clearly between:

• changes that are safe and obvious
• changes that are likely right but still somewhat judgmental
• ambiguous duplicates or restructures that should not be applied silently

Important proposal requirements:

1. Call out every file you expect to create or update.
2. Call out every file you expect to rename or move.
3. Call out any ambiguous duplicates you will not merge automatically.
4. State whether SCHEMA.md or index.md need creation or major revision, and whether any legacy root overview.md should be consolidated and removed.
5. State whether link-style normalization will be partial or broad.
6. Call out the guidance files you expect to update.
7. Call out any guidance sections you expect to shorten and replace with wiki pointers.
8. Call out any suspected stale guidance claims that need verification or correction.
9. Call out mirror files you will intentionally leave thin or untouched.
10. In --guidance-only mode, set all wiki-structure proposal sections such as create/update, rename/move, link normalization, and backlink repairs to None unless a guidance file itself is the item being updated.

After presenting the proposal, ask:

"Does this alignment proposal look right? If yes, I'll apply it. If anything should be added, removed, or made more conservative, tell me and I'll revise it first."

Wait for explicit confirmation before editing files.

Phase 4 — Apply the alignment

Once the user confirms, apply the smallest safe set of changes needed to align the wiki.

Safe full-alignment work includes:

1. creating or updating <wiki root>/SCHEMA.md
2. creating or updating <wiki root>/index.md as the single root hub with a concise ## Overview section near the top
3. consolidating a legacy root <wiki root>/overview.md into index.md and removing it when safe
4. normalizing obvious durable category-note filenames to kebab-case
5. normalizing obvious internal links to [[kebab-case-note-name]]
6. updating inbound references when filenames change
7. adding reciprocal backlinks where the relationship is clearly material
8. creating missing category directories when the current scope clearly benefits from them
9. moving notes into clearer category locations when the destination is obvious and safe
10. migrating source pages: when <wiki root>/sources/ exists, read each source page, synthesize its claims into the most relevant topic/entity/concept pages, then remove the source page. Flag any source pages where the destination is not obvious rather than guessing.
11. auditing and updating relevant AGENTS.md / CLAUDE.md files so they point to the wiki and keep operational guidance concise
12. shortening duplicated deep-reference sections in guidance files into concise wiki pointers when the durable detail already belongs in the wiki
13. correcting clearly stale guidance after verifying against current repo state, guidance scope, and the wiki
14. keeping mirror files thin when they intentionally defer to a canonical guidance file
15. appending a parseable entry to <wiki root>/log.md like:

## [YYYY-MM-DD] alignment | <scope>

In --guidance-only mode, restrict the work to items 10-13 above. Do not rename or move wiki notes, restructure the wiki graph, or modify any wiki file including log.md.

When renaming or moving notes:

• preserve the content
• preserve the durable identity
• update obvious inbound references
• avoid partial graph breakage

When updating guidance files:

• preserve commands, hard rules, safety constraints, scope boundaries, and canonical source-of-truth pointers
• prefer concise pointers into the wiki over long duplicated deep-reference prose
• verify stale-looking claims against current repo state before changing or removing them
• keep mirror files like CLAUDE.md thin when they intentionally defer to AGENTS.md

Do not:

• silently merge ambiguous duplicate notes
• flatten meaningful disagreements
• rewrite raw-source files
• perform broad speculative synthesis during alignment
• turn AGENTS.md / CLAUDE.md files into shadow wiki pages
• rewrite every scoped guidance file in a monorepo when the target scope does not require it

If a case is ambiguous, leave it unresolved and report it explicitly.

Phase 5 — Report back

After applying the alignment, output:

Alignment applied to <wiki root>

### Mode

- <full alignment or guidance-only>

### Guidance files updated

- <path or "none">

### Created or updated

- <path>

### Renamed or moved

- <old path> -> <new path>

### Left unresolved

- <issue or "none">

### Next useful command

- `/do-wiki-lint [scope]`

If the scope was already close to the target conventions and only small repairs were needed, say so explicitly.

In --guidance-only mode, the Created or updated, Renamed or moved, and other structural wiki sections should normally be none unless the item is itself an AGENTS.md or CLAUDE.md file.

Rules

• Proposal first. Do not edit anything before explicit confirmation.
• Prefer the smallest safe alignment over a broad rewrite.
• Durable category-note filenames use kebab-case. Special root files keep their fixed names.
• Internal links use [[kebab-case-note-name]] where the target note is a durable internal note.
• Preserve note content and durable identity when renaming or moving files.
• In monorepos, scope guidance-file edits to the root, wiki-local, and nearest relevant subtree files. Do not fan out across unrelated modules.
• Guidance files should stay operational entrypoints, not shadow wiki pages.
• In --guidance-only mode, edit only AGENTS.md / CLAUDE.md files. The wiki is read-only context in that mode.
• Do not silently merge ambiguous duplicates.
• Do not modify raw-source files.