yzr-llm-workspace-management

LLM Workspace Management

Maintain alocal multi-wiki workspace's "global view" and cross-wiki orchestration—single-wiki ingest / query / lint goes through yzr-llm-wiki-management skill. This skill stands above all wikis and does things that require cross-wiki judgment.

Two deliverables:

SKILL.md (this document)—workflow + boundaries
Deterministic execution belongs to the llmw CLI—this skill zero code, converges to two commands; when inconsistent, the detector prevails:
- llmw check-fixtures: detect only (output a drift report, do not write to disk)
- llmw upgrade: workspace skeleton + per-wiki aggregate deterministic upgrade (dry-run by default)

Input / Output

Information required at startup

Information	Source	Notes
Workspace path	`$LLMW_WORKSPACE` or default `~/yzr-llm-wiki-workspace` or ask interactively	The CLI usually sets the variable on enter
Operation type	User natural language	scan / query / link / lint / upgrade
Query scope (query only)	User natural language or explicitly specified wiki name	If unspecified, use global INDEX routing

Operation artifacts

scan → write <workspace>/INDEX.md + <workspace>/STATS.md(format A2/A3)
query → the conversation gives the answer (with per-wiki citations); optionally archive <workspace>/cross_queries/<slug>.md (format A4)
link → via yzr-llm-wiki-management ingest flow, add cross-wiki links in the involved wikis
lint → write <workspace>/LINT.md(format A5) + conversation summary
upgrade → run llmw upgrade(dry-run by default, add --apply [--yes] to write to disk); 3 final-state JSON is output by the CLI; see §6 for details

Execution principles / boundaries

Boundaries with the workspace CLI

When this skill is present, it may call llmw—read / detect / upgrade commands are executed directly (for subcommands and parameters see llmw --help, not enumerated); for commands that modify workspace / wiki metadata or affect a running session, give the user the complete command for confirmation before executing.

Do not hand-write toml—metadata writes must go through the CLI (schema validation / atomic writes / uniqueness constraints are guaranteed by the CLI).Commands involving api_key are always executed by the user personally(secrets do not pass through the agent).

Boundaries with yzr-llm-wiki-management

Single-wiki operations (ingest / query / lint / writing files within a wiki) are always delegated to yzr-llm-wiki-management— this skill does not directlyedit <wiki>/wiki/**(maintain log.md synchronization, frontmatter, and other invariants). This skill only does workspace-level things: scan aggregation / routing / cross-wiki synthesis and comparison / cross-wiki link suggestions / workspace lint / cross-wiki memory.

Artifacts this skill may write (invariants, mandatory)

File / Directory	Who writes	Boundary
`<workspace>/INDEX.md`	This skill	Aggregate write during scan
`<workspace>/STATS.md`	This skill	Aggregate write during scan
`<workspace>/cross_queries/`	This skill	Cross-wiki synthesis Q&A archive
`<workspace>/LINT.md`	This skill	Workspace-level lint report
`<workspace>/MEMORY/` in the `*.md` + sync `MEMORY.md` index	This skill	Cross-wiki experience only (single-wiki experience belongs to `<wiki>/MEMORY/`）

Violating attribution = bug. For the full attribution table + quadrant table, see <workspace>/AGENTS.md 's sections "Boundaries of this workspace" + "Discipline of this file itself" (including the skeleton ownership quadrant table) (byte-owned template rendering).

Workflow / Steps

0. Startup check

Every time you enter this skill:

Locate the workspace path:$LLMW_WORKSPACE → default ~/yzr-llm-wiki-workspace → ask interactively
Verify that <workspace>/workspace.toml exists—if not, prompt the user "workspace hasn't been init'd yet, run llmw init to initialize" (do notrun it on the user's behalf)
Load the cross-wiki MEMORY index: when working at the workspace root, it is automatically loaded via <workspace>/AGENTS.md 's @MEMORY/MEMORY.md import; when working outside the root directory / reading AGENTS.md natively, it does not expand @ 's agent → explicitly Read <$LLMW_WORKSPACE>/MEMORY/MEMORY.md fill it in
Load the scope boundaries: when the agent cwd is inside the <wiki>/ subdirectory and it switches to running yzr-llm-wiki-management , this skill's discipline does not take over; the <wiki>/AGENTS.md single-wiki discipline takes effect
do notautomatically run scan—wait for the user to give an operation intent

1. Scan / refresh-index

Trigger: "scan the workspace" / "update INDEX.md" / the user says "the workspace needs a refresh".

Process：

Read <workspace>/workspace.toml to get the [wikis] registry
For each wiki:
- Read <wiki>/wiki_metadata.toml(CLI-maintained)
- Read <wiki>/AGENTS.md 's "Boundaries of this wiki" section (to get the boundaries)
- Read <wiki>/wiki/index.md(existing content + paragraph skeleton)
- Scan <wiki>/wiki/{entities,concepts,sources,comparisons,syntheses}/ to get page counts
- Scan <wiki>/raw/ recursively to get the raw material count (count only, do not read contents)
- Read <wiki>/wiki/log.md 's last entry to get last activity
- Read <wiki>/MEMORY/ to get the memory files count (file names only)
Read <workspace>/MEMORY/MEMORY.md index, aggregate according to the A2 sorting rules, write INDEX.md + STATS.md (format A2/A3)
Atomic write (POSIX tmp + fsync + rename）
Report in conversation: "Refreshed INDEX.md / STATS.md, X wikis, Y pages, Z raw materials"

When not to scan: if the user only wants to do a query → use the existing INDEX.md first; if INDEX.md is missing or clearly outdated (cannot cover newly added wikis), then prompt to scan first.

2. Query (cross-wiki Q&A)

Trigger: "summarize the content about X across all my wikis" / "compare A and B on Y" / "which wiki should I check for X".

4 modes + determination priority local > compare > route > synthesis：

Mode	Trigger keywords	Process
local	"Only look at wiki X" / "Look up Y in X"	delegate `yzr-llm-wiki-management` query
compare	"Compare A and B" / "The difference between A and B"	Read both sides' wiki/index.md → query → diff-style comparison
route	"Which wiki should I look up" / "Which wiki does this belong to"	Read INDEX.md → match by topic / tag / description → return 1-3 candidate wikis
synthesis	"Summarize all" / "Synthesize all wikis" / fallback	route → query each candidate wiki → merge + annotate the source of each wiki

a good query must have an "whether to archive" step——Archive location:

The answer involvessingle wiki → <wiki>/wiki/syntheses/<slug>.md(go through yzr-llm-wiki-management）
The answer involvesmultiple wikis → <workspace>/cross_queries/<slug>.md(written directly by this skill, format A4)

When the archived body text cites upstream volatile facts, it must pass the perception test—for the rule SSOT see yzr-llm-wiki-management 's references/ingest-workflow.md"Stability of body-text citations" section.

3. Link (cross-wiki cross-references)

Trigger: "entity X in wiki A also exists in wiki B, add a link" / "scan for duplicate entities across wikis".

Process：

Scan: for each wiki's wiki/entities/ + wiki/concepts/, extract all entity names (frontmatter title or filename slug)
Deduplicate and aggregate: collect entities with the same name / similar meaning across wikis (compared using description) as candidate pairs
Suggest: list the candidate pairs in the conversation and let the user choose which ones to add cross-wiki links to
Write: after user confirmation, for each wiki involved, call yzr-llm-wiki-management 's ingest process to update the corresponding entity / concept page—append a "cross-wiki references" section (for the xref format see <workspace>/AGENTS.md 's "cross-wiki conventions" section)

4. Lint (workspace-level)

Trigger: "workspace lint" / "workspace health check" / periodically (e.g., incidentally on each scan).

Process：

workspace-level deterministic checks(inline in agent):
- Duplicate entities across wikis (pairs with the same name + different slugs)
- Broken cross-wiki links (cross_queries/*.md's sources path does not exist;<wiki>/wiki/** in ../<another-wiki>/... path does not exist)
- Unregistered wiki subdirectories (present on disk as <wiki>/AGENTS.md but not registered in workspace.toml)
- Wikis registered in workspace.toml but not present on disk (orphan registrations)
- Whether the wiki lists in STATS.md and INDEX.md are consistent
- MEMORY index consistency: scan <workspace>/MEMORY/*.md(excluding MEMORY.md), any file not listed in the MEMORY/MEMORY.md index → report memory-not-indexed（severity = info）
Semi-qualitative checks：
- Whether wikis with overlapping topics need to be merged
- Whether the tag system is chaotic (same tag name with different meanings / same meaning with inconsistent tag names)
What this skill does not do: single-wiki internal lint—hand off to yzr-llm-wiki-management
Output: write <workspace>/LINT.md(format A5) + report in the conversation

When not to lint: user only asks query → no lint; user says "scan" → scan rather than lint.

5. Memory (cross-wiki agent private memory)

Trigger: proactively write when cross-wiki information worth preserving is identified during scan / query / link / lint.cross-wikiinformation worth preserving is identified, write proactively.

One-line criterion:cross-wikipreference/association/pattern/experience → write;single-wikiobservation → hand off to yzr-llm-wiki-management；cross-wiki synthesized answer itself → archive cross_queries/；one-off observation → direct chat.

Complete "when to write / not write" + criterion scale canonical = <workspace>/AGENTS.md 's "Memory Discipline" section (byte-owned template rendering), not repeated in this appendix.

Process：

identify observation worth preserving → scope self-check confirms cross-wiki
determine entry form (full / short)
write to MEMORY/<slug>.md(full entry) or directly append a one-line short entry in MEMORY/MEMORY.md Append one short entry line
sync MEMORY.md index one line(missing write = unreadable next time, lint memory-not-indexed fallback)

do not touch <workspace>/INDEX.md / STATS.md / LINT.md / any <wiki>/MEMORY/。

6. Upgrade (upgrade workspace skeleton)

Trigger: "upgrade workspace / check workspace version / format upgrade".

llmw upgrade(CLI) = all deterministic operations — workspace skeleton + per-wiki aggregation two-stage, handled by classification per <workspace>/AGENTS.md 's "Discipline of this file itself" section (including skeleton ownership four-way table).llmw check-fixtures only probes (does not write to disk). agent = run commands + interpret output.

Process：

llmw upgrade default dry-run → output workspace + each wiki's processing plan + 3 terminal-state JSON (add --json machine-readable)
interpret 3 terminal states：
- done → wrap up, prompt user "workspace upgrade complete, X wikis upgraded"
- blocked_drift → per hint field move custom content to MEMORY/, then llmw upgrade --apply --yes rerun
- verify_failed → report to user, hand off to human
each wiki's subsequent content migration goes through yzr-llm-wiki-management workflow — this skill does not run it on behalf

do notwrite INDEX.md / STATS.md / LINT.md(upgrade is not a scan / lint event). Upgrade only touches byte/block/header-owned file types, does not touch secret-containing config.

Reference examples

Example 1: cross-wiki synthesized Q&A

User: "What records do all my wikis have about RAID?"

skill reads <workspace>/INDEX.md → finds huawei_storage_wiki 's description contains "storage"
mode = synthesis
hand off yzr-llm-wiki-management to huawei_storage_wiki to do query: "RAID"
get answer (with source page references), give to user in conversation, attach "only involves 1 wiki, whether to archive to huawei_storage_wiki/wiki/syntheses/raid-overview.md？"
user confirms → go through yzr-llm-wiki-management write synthesis page + log entry

Example 2: routing

User: "I just downloaded an LLM inference paper, which wiki should it go in?"

skill reads INDEX.md + reads each wiki's description / tags
mode = route
returns: "huawei_storage_wiki topic is storage, irrelevant;test The wiki topic is test, which is also unrelated; suggest creating a new wiki (llmw wiki --name=llm-inference add ...）"
Propose running on behalf of llmw wiki --name=llm-inference add—executed after user confirmation (the skill performs routing when present, closing the loop in passing)

Reference files

Required reading：<workspace>/AGENTS.md（= workspace-agents-md-template.md Template-rendered draft, byte-owned)—the canonical workspace-level contract
Single-wiki contract：yzr-llm-wiki-management SKILL.md + references/ (when this skill reads wiki files it interprets them according to their contract, and does not write directly)
CLI documentation: workspace CLI (command llmw, maintained in the same repository as this skill)—init / add / remove / config / enter / model ... Command reference is here

Appendix: artifact format contracts and read contracts

The appendix carries the format contracts for files the skill writes to disk. For read contracts and instance ownership, see <workspace>/AGENTS.md。

A1. workspace.toml read contract

Path:<workspace-root>/workspace.toml
The authoritative full schema is in the CLI code;workspace-toml-reads-satisfied check verifies the completeness of the read contract

Fields actually read by the skill（scan / upgrade for):

Field	Purpose
`templates_version`	`llmw upgrade` Version comparison + automatic bump (including `workspace_format` / `wiki_format` two-component)
`[wikis.<name>].path`	skill `scan` Iterate over wiki subdirectories
`[wikis.<name>].created_at`	wiki ordering within INDEX

A2. INDEX.md

Maintainer:skill written by the skill during scan; not written by CLI scan when written; CLI does not write
frontmatter required (A7) + type: workspace-index；title recommended "Workspace Index"；tags recommended [workspace, index]

Body skeleton:

# <Workspace Display Name> — Workspace Index

> workspace 入口文档。每个 wiki 一节，按 wiki name 字母序；同字母序内按 `created_at` 升序。

## Wikis

### <wiki-name>

- **display_name**: ...
- **topic**: ...
- **description**: ...
- **tags**: [...]
- **created**: YYYY-MM-DD
- **last activity**: YYYY-MM-DD (log entry kind)
- **page counts**: 0 entities / 0 concepts / ...
- **key entities**: [...]
- **one-line summary**: ...

## Cross-wiki Links
...（短描述）
## Recent Activity (across all wikis)
...

A3. STATS.md

Maintainer:skill also written by the skill during scan; difference from INDEX.md: structured (table) scan is written together; difference from INDEX.md: structured (table)
frontmatter required (A7) + type: workspace-stats
Body skeleton:# <Workspace> — Workspace Stats + ## Overview summary table + ## Per-wiki one sectioned table per wiki (pages / entities / concepts / sources / comparisons / syntheses / raw_files / last_log_entry / tags / memory_files)
Skill write scenarios:scan(same refresh as INDEX.md)

A4. cross_queries/

Maintainer:skill written by the skill when query output is suitable for archiving query when the output is suitable for archiving Write
File naming:<slug>.md，kebab-case ^[a-z0-9][a-z0-9-]*$（A8）
frontmatter required (A7) + type: cross-query；tags recommended [workspace, cross-query, <涉及 wiki 的 tag>...]; required sources(array of paths referencing pages within the wiki) + wikis(array of involved wiki names)
Skill write scenarios:query when output is confirmed by the user for archiving

A5. LINT.md

Maintainer:skill written by the skill during lint as the most recent report ( lint when writing the most recent report (notaccumulated; overwritten on every lint, it is a snapshot)
frontmatter required (A7) + type: workspace-lint
Body skeleton:# <Workspace> — Lint Report (<YYYY-MM-DD>) + ## Per-wiki Issues(one paragraph per wiki; lint within this wiki goes through yzr-llm-wiki-management) + ## Workspace-level Issues(cross-wiki duplicate entity / unregistered subdirectory / stale STATS / MEMORY index consistency / ...)
Skill write scenarios:lint(overwritten every time)

A6. workspace MEMORY/

Maintainer: CLI creates an empty directory during init + writes MEMORY/MEMORY.md index placeholder; subsequent entries are written by skill write + synchronously append one index line to MEMORY.md. Humans do not write; CLI does not write
MEMORY is not mandatorily listed in INDEX.md (agent-private entry point)
Entry form (full / short) + when to write / not write + index line format canonical = <workspace>/AGENTS.md the "Memory discipline" section (byte-owned template rendering), not repeated in this appendix

A6.1 MEMORY/MEMORY.md (index)

No frontmatter (inline-loaded by <workspace>/AGENTS.md using @MEMORY/MEMORY.md @import inline load); body: top 1 paragraph of description + ## 索引 section (full/short two formats coexist).

A6.2 MEMORY/*.md (non-MEMORY.md)

frontmatter only title required;type if written, fixed workspace-memory(aligned with the wiki-side MEMORY decoupling convention);created/updated/tags/description/wikis all optional. lint memory-not-indexed as fallback; inbound links are not mandatory, and it is not listed in INDEX.md.

A7. General rules for Frontmatter fields

5 generally required items(workspace-level markdown,MEMORY/*.md exception—see A6.2）：

Field	Type	Description
`title`	string	without extension
`type`	enum	see table below
`tags`	array	nullable
`created`	date	`YYYY-MM-DD`
`updated`	date	`YYYY-MM-DD`

type values(workspace-level markdown):

`type`	Notes
`workspace-index`	`<workspace>/INDEX.md`(unique)
`workspace-stats`	`<workspace>/STATS.md`(unique)
`workspace-lint`	`<workspace>/LINT.md`(unique)
`cross-query`	`<workspace>/cross_queries/<slug>.md`
`workspace-memory`	`<workspace>/MEMORY/*.md`(if type is written; optional)

Type-specific fields：

Field	Applicable type	Required	Meaning
`sources`	`cross-query`	Yes	array of referenced wiki internal page paths (relative to workspace root)
`wikis`	`cross-query` / `workspace-memory`	`cross-query` Yes / `workspace-memory` recommended	list of involved wiki names
`description`	All	Recommended	one sentence

FieldSemanticsWriting method (how to write well title / description / tags）SSOT = yzr-llm-wiki-management page-templates.md §1.

A8. Naming constraints

This table only carries skill files written to disknaming constraints (these files are not read or written by CLI and have no mechanical gate; the sole carrier of the constraints = this section). wiki name (llmw wiki add validated at creation) and CLI internal identifiers belong to CLI; for recommended wiki naming style see <workspace>/AGENTS.md the "cross-wiki conventions" section.

Dimension	Rule	Applicable object
cross_query slug	kebab-case `^[a-z0-9][a-z0-9-]*$`	`cross_queries/<slug>.md`
MEMORY file names	kebab-case `^[a-z0-9][a-z0-9-]*$`	`<workspace>/MEMORY/*.md`(MEMORY.md excepted)
frontmatter field names	strictly lowercase + underscores	all workspace-level markdown
frontmatter `type` values	strictly lowercase + hyphens (`workspace-index` / `workspace-memory` etc.)	all workspace-level markdown

About this skill

Input / Output

Information required at startup

Operation artifacts

Execution principles / boundaries

Boundaries with the workspace CLI

Boundaries with yzr-llm-wiki-management

Artifacts this skill may write (invariants, mandatory)

Workflow / Steps

0. Startup check

1. Scan / refresh-index

2. Query (cross-wiki Q&A)

3. Link (cross-wiki cross-references)

4. Lint (workspace-level)

5. Memory (cross-wiki agent private memory)

6. Upgrade (upgrade workspace skeleton)

Reference examples

Example 1: cross-wiki synthesized Q&A

Example 2: routing

Reference files

Appendix: artifact format contracts and read contracts

A1. workspace.toml read contract

A2. INDEX.md

A3. STATS.md

A4. cross_queries/

A5. LINT.md

A6. workspace MEMORY/

A6.1 MEMORY/MEMORY.md (index)

A6.2 MEMORY/*.md (non-MEMORY.md)

A7. General rules for Frontmatter fields

A8. Naming constraints