# Agent Spec Wiki

> Use when initializing, checking, enriching, or reviewing agent-spec code live wiki pages, source_files trace, or Rust architecture inventory.

- Skill: `zhanghandong/agent-spec-wiki` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhanghandong/agent-spec-wiki`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhanghandong/agent-spec-wiki/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ZhangHanDong (https://skillmd.com/u/zhanghandong)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhanghandong/agent-spec-wiki

---


# Agent-Spec Code Live Wiki Workflow

> **Version:** 1.0.0 | **Last Updated:** 2026-08-14 | **Tracks:** agent-spec 1.4.0

Use this skill for repo-local code live wiki maintenance and review.

## Rules

- Treat `.agent-spec/wiki/` as agent working memory, not KLL truth.
- Put durable truth in `knowledge/`, executable contracts in `specs/`, and
  reader-authored docs in `docs/`.
- Keep `.agent-spec/wiki/**` as tracked live wiki memory when the project wants it in git;
  keep `.agent-spec/runs`, `.agent-spec/trace`, temp files, and runtime state
  ignored.
- Preserve `source_files` frontmatter in every maintained wiki article.
- Before broad source reading, run `wiki status` and prefer fresh wiki articles
  when they cover the needed area.
- Use `wiki query <text>` before opening many files, and use `wiki inspect
  <path>` when you need the wiki pages, KLL requirements, and task specs related
  to a source or knowledge path.
- After code or architecture changes, update affected articles, run `wiki index`,
  then run `wiki lint` or `wiki check`.
- Archive old wiki material into `learnings/` or `archive/` summaries with
  source links instead of deleting it abruptly.
- Non-goals: no built-in LLM long-form wiki generation, no web UI, and no
  replacement for KLL requirements or decisions.
- Rust architecture inventory is deterministic Cargo metadata; prose remains
  agent-authored and must cite source files.
- Reject symlinks in source, article, and architecture traversal. The CLI has no
  generated `docs/wiki` compatibility mode; `.agent-spec/wiki` is the single
  maintained wiki model.

## Workflow

```bash
agent-spec wiki init --code . --wiki .agent-spec/wiki
agent-spec wiki seed --code . --wiki .agent-spec/wiki
agent-spec wiki seed --code . --wiki .agent-spec/wiki --check
agent-spec wiki status --code . --wiki .agent-spec/wiki
agent-spec wiki query "intent compiler" --wiki .agent-spec/wiki
agent-spec wiki inspect src/spec_wiki/live.rs --code . --wiki .agent-spec/wiki
agent-spec wiki inventory --code . --format json
agent-spec wiki inventory --code . --format mermaid
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format json --out .agent-spec/wiki/architecture/project-map.json
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format mermaid --out .agent-spec/wiki/architecture/project-map.mmd
agent-spec wiki inspect-project brain-rs --code . --wiki .agent-spec/wiki --format text
agent-spec wiki index --wiki .agent-spec/wiki
agent-spec wiki lint --code . --wiki .agent-spec/wiki
agent-spec wiki check --code . --wiki .agent-spec/wiki
agent-spec wiki meta update --code . --wiki .agent-spec/wiki
bash scripts/docs-lint.sh
```

## Article Format

```markdown
---
title: "Parser"
type: module
source_files:
  - src/spec_parser/parser.rs
tags:
  - parser
---

# Parser
```

## Architecture

For Rust projects, `wiki inventory` writes a Rust architecture inventory model
from Cargo metadata and can render a Mermaid graph. For non-Rust projects, the
generic inventory still supports code live wiki status, index, lint, and
metadata.

Generated architecture files:

- `.agent-spec/wiki/architecture/inventory.json`
- `.agent-spec/wiki/architecture/workspace.mmd`
- `.agent-spec/wiki/architecture/modules.mmd`

The wiki compounds project understanding over time; it is not regenerated as a
large batch of shallow file summaries.

## Cross-Project Wiki

Use project articles for important dependent projects and flow articles for
working mechanisms or data flow between projects.
Both article types must be regular Markdown files. Do not use symlinks: project
map discovery and `wiki init --check` reject them explicitly.
Every field shown below is required and non-empty. Treat malformed lines,
duplicate keys, or missing fields as article errors; do not generate a partial
project map from them.

- Project articles: `.agent-spec/wiki/projects/*.md`
- Flow articles: `.agent-spec/wiki/flows/*.md`
- `source_files`: repo-local files that drive stale checks
- `external_sources`: outside paths, URLs, or repo ids recorded as evidence
  labels; agent-spec performs no external repository scan by default

Project article example:

```md
---
title: "brain-rs"
type: external-project
project_id: brain-rs
repo: rust-agents/brain-rs
role: "Context provider"
interfaces: [cli, json]
protocols: [stdio]
status: active
source_files:
  - src/integration/brain.rs
external_sources:
  - https://example.invalid/rust-agents/brain-rs
---
# brain-rs
```

Flow article example:

```md
---
title: "agent-spec to brain-rs context flow"
type: project-flow
flow_id: agent-spec-to-brain
projects:
  - agent-spec
  - brain-rs
kind: calls
protocols: [stdio, json]
requirements:
  - REQ-CROSS-PROJECT-WIKI
specs:
  - specs/task-cross-project-wiki.spec.md
source_files:
  - src/integration/brain.rs
external_sources:
  - https://example.invalid/rust-agents/brain-rs/src/lib.rs
---
# agent-spec to brain-rs context flow
```

The `projects` list is ordered; each adjacent pair becomes a directed edge.
`requirements` and `specs` resolve inside the current repository. Put paths,
URLs, and repository identifiers from outside the current repository in
`external_sources` only.

After editing project or flow articles, run:

```bash
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format json --out .agent-spec/wiki/architecture/project-map.json
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format mermaid --out .agent-spec/wiki/architecture/project-map.mmd
agent-spec wiki index --wiki .agent-spec/wiki
agent-spec wiki check --code . --wiki .agent-spec/wiki
```

The project-map JSON and Mermaid output are derived artifacts. The maintained
truth remains the project articles and flow articles.
`wiki lint` and `wiki check` require both derived artifacts to exist and match
the maintained project and flow articles exactly.