VI EN
⚙️ Not installed yet? Open the install page first. Then come back and choose your role.

## 📖 What is contextd?

A shared playbook for people and AI. Document how your team works in the wiki. AI reads it first and follows your standards.

🏢

#### Workspace

One company or project uses one workspace. Do not mix knowledge between workspaces.

📦

#### Pack

A pack is a ready guide for one type of work (web-api, frontend-react, ai-app, product, and more).

📜

#### Contract

A contract is a fixed format (API shape, data format, error code). Do not change it by yourself.

🧩

#### Pattern

A pattern is a recommended way to solve a common problem. Reuse it when possible.

🎯

#### Brief / OKR

Product briefs, goals, users, and metrics — non-technical product knowledge. Requires `pack-product`.

🔍

#### Evidence

Steps to turn notes into trusted wiki content: ingest → analyze → QA → apply.

## 1Who are you?

Choose your role to see the simplest first steps.

💼

### Non-technical (PM / Business / Product Owner)

You do not need to write code. You only need to describe goals, users, and product context.

Start here if you are in product/business
🛠️

### Engineer

You write code and want AI to follow your team’s contracts and patterns. You need wiki-aware code generation.

Start here if you write code
📚

### Wiki Maintainer

You set up and maintain the team wiki — ingest knowledge, define rules, and keep wiki content aligned with real code.

Start here if you maintain the wiki
🔧

### Self-builder / Domain Expert

You work in another field (mechanical, accounting, healthcare, etc.) and use Claude Code as a self-builder tool to create apps that support your work.

Start here if you are not a developer but build your own tools

### 💼 Guide for non-technical users

PM, Product Owner, Business Analyst, Stakeholder. No coding knowledge needed.

1

#### Ask your team for the workspace name

You do not need to create a workspace yourself. Just use your team’s workspace name. In Claude Code, run `/list-workspaces` to see all workspaces.

    /list-workspaces

2

#### Need a simple explanation for technical terms?

If you see a term you do not know, run `/contextd-explain topic`. You will get a simple explanation with examples.

    /contextd-explain circuit-breaker --depth tldr
    /contextd-explain mqtt-topic-contract --depth short

3

#### Create your first product brief (guided prompts)

The system asks business questions: problem, users, success metrics, and timeline. No technical answers required.

    /product-brief "Reduce signup friction for mobile users"

The result is saved automatically. You only need to fill remaining TODOs.

💡 Next: When you need to explain a feature to leadership/business/customer support, run `/business-view {service-name}` — it outputs a plain-language document auto-synced with the engineering doc.

### 🛠️ Guide for Engineers

Backend / frontend / fullstack / mobile developers. You write code; AI reads the wiki first and generates code aligned with team rules.

1

#### Connect the wiki to your current codebase

First time in a new codebase: this command detects project name + tech stack and creates `.claude/wiki.json` connected to your workspace.

    /contextd-setup

If the workspace does not exist yet, run `/new-workspace project-name` to create one.

2

#### Quickly find rules/contracts before coding

Use `/find {keywords}` to quickly locate rules in the wiki.

    /find idempotency retry
    /find rest error shape

3

#### Write wiki-aligned code for larger tasks

Before EVERY task (implement feature, fix bug, design, incident, review), run `/use-contextd` to run a pre-check workflow before coding and reduce mistakes.

    /use-contextd implement payment refund flow with idempotency

Goal: keep code aligned with team agreements and avoid invented APIs.

💡 Next: After code is merged, run `/update-contextd` to sync wiki updates. Run `/rebase-contextd` periodically to fix wiki/code drift.

### 📚 Path for Wiki Maintainers

You set up wiki for a new team, or bootstrap a workspace from an existing codebase.

1

#### Create a new workspace

The wizard asks for metadata (company, role, period, stack, packs), then scaffolds full folders + workspace.md + an empty patterns-index.md.

    /new-workspace acme-corp

2

#### Bootstrap knowledge from an existing codebase

If the team already has a legacy codebase, run `/code-analyze` to snapshot it → the system proposes rules, contracts, and architecture from real code.

    /code-analyze
    /evidence-qa
    /evidence-apply

3

#### Generate an overview report for the team

A self-contained HTML file covering the full workspace (Overview / Architecture / Contracts / Patterns / Domains / ADRs / Runbooks).

    /contextd-report

Open the HTML file directly in a browser — no server required.

💡 Next: Run `/contextd-eval` periodically to measure wiki quality (hallucination rate, knowledge gaps, plan-block rate). If you suspect drift, run `/rebase-contextd`.

### 🔧 Guide for Self-builders / Domain Experts

You are a domain expert from another field (mechanical, accounting, healthcare, legal, education, etc.) using Claude Code as a personal builder assistant. You have ideas but need help starting.

1

#### Enable Solo Builder mode

Easiest way: run `/tool-design` directly — the system asks setup questions and enables the pack for you.

Manual way: run `/contextd-setup` → in pack selection, tick `pack-solo-builder`.

To apply this for all projects in the workspace, edit `workspace.md` under `## Packs`:

    ## Packs

    - pack-solo-builder

2

#### Design your first tool from an idea

Unclear ideas are okay. The system asks 6-8 questions (each with examples + an "I don't know" option), draws a system map, checks existing tools to avoid duplicates, then recommends a suitable approach.

    /tool-design "tool to calculate steel beam bending moment"
    /tool-design "manage workshop component inventory"
    /tool-design "pull USD/VND exchange rate every morning"

Result: a design spec with system map, chosen technology + rationale, setup guide for Linux and Windows, and acceptance criteria.

3

#### Turn the design into code

When the design spec is complete (no open questions), ask Claude Code to implement exactly from that spec:

    implement spec at workspaces/{ws}/tools/{slug}-spec.md

Claude will implement according to the design spec — without changing technology choices on its own.

💡 Next: Use `/tool-list` to review existing tools (avoid duplicates). Use `/tool-extend tool-name` to add features. On Windows, Claude may recommend Docker for complex setup.

## 2Core concepts (3-minute read)

Understanding these five concepts is enough for daily wiki usage.

Workspace (isolated knowledge base per company/project)
  Each company/project gets its own workspace folder. Knowledge is never mixed across workspaces, because each organization has different rules. The active workspace is defined in `.claude/wiki.json`.
Pack (technology-specific knowledge bundle)
  Wiki-template is stack-agnostic. Specialized knowledge (Kafka, REST, React, AI app, product, etc.) lives in `packs`. Enable/disable packs in `/contextd-setup` pack selection, or edit `workspace.md`. There are currently 13 packs (see section below).
Contract vs Pattern
  Priority order: Contract > Pattern > Project docs > Domain knowledge. Contract = fixed agreement (API shape, data format) — must not be changed arbitrarily. Pattern = preferred implementation approach — should be reused, with exceptions only when justified.
Slash command vs internal workflow
  Commands (`/use-contextd`, `/find`, ...) are what you invoke directly. Internal workflow (planner, context-selector, reviewer, ...) runs automatically in the background.
Evidence ingestion workflow
  4 steps: `/evidence-ingest` → `/evidence-analyze` → `/evidence-qa` → `/evidence-apply`. Use this when external sources (Confluence, Linear, pasted notes, code) need to be validated before entering the wiki. Raw source data remains immutable after ingest. Each workspace stays fully isolated.

## 3Command reference (cheat sheet)

Tags: tech for engineers · nontech no coding needed · maint for wiki maintainers.

### 🏁 Workspace setup & navigation

Command | Purpose | When to use
--- | --- | ---
/contextd-setuptech | Create `.claude/wiki.json` for the codebase, detect project name + components | First time using wiki with a codebase
/contextd-detecttech | Validate `wiki.json`, scan dependency, propose update | After setup, or when troubleshooting
/switch-workspace nametech | Switch the active workspace for the current codebase | One codebase serving multiple domains
/new-workspace project-namemaint | Create a new workspace from template | Joining a new company/project
/list-workspacesnontech tech | List all workspaces and highlight active one | Check which workspaces exist

### 🧠 Wiki usage (per-task)

Command | Purpose | When to use
--- | --- | ---
/use-contextdtech | Load the right wiki context before Claude writes code | Before each task: implement, bug fix, design, review
/find {keywords}tech | Find related rules and docs quickly | Use when you know the keyword but need the exact file
/update-contextdtech | Save important code changes back to wiki | Run after merge so wiki stays up to date
/rebase-contextdmaint | Check wiki against code and suggest fixes | Run weekly/monthly, or when wiki looks outdated

### 💼 Non-tech contributors (Product / Business)

Command | Purpose | When to use
--- | --- | ---
/product-brief [title]nontech | Guide to create product brief: Problem / Users / Success metrics / Acceptance criteria | When PM creates a new brief before handing off to engineering
/business-view {target}nontech | Translate technical docs into plain business language | Explain features to leadership/business/support
/contextd-explain topicnontech | Explain a term/rule in plain language | When you hit unfamiliar terms while reading wiki

Requirement: Workspace must enable `pack-product` — easiest path: run `/contextd-setup` Step 4.5 and tick `pack-product`. Or run `/product-brief` and let it guide enabling.

### 🔧 Solo builder (Non-tech experts using Claude Code as a no-code IDE)

Command | Purpose | When to use
--- | --- | ---
/tool-design "idea"nontech | Discovery wizard → system map → recipe match → recommended stack → write spec (NO code generation) | When you have a new tool idea but do not know where to start
/tool-listnontech | List created tools grouped by status | Check existing tools before creating new ones (avoid duplicates)
/tool-extend tool-namenontech | Propose upgrades for existing tools — add features, adjust scope | When an existing tool needs enhancements

Requirement: Workspace enables `pack-solo-builder` (slash `/tool-design` can enable it). Cross-platform recipes: Linux native + Docker recommendation on Windows for complex dependencies.

### 📊 Reporting

Command | Purpose | When to use
--- | --- | ---
/contextd-reportmaint | Single standalone HTML file — Overview / Architecture / Contracts / Patterns / Runbooks | Onboard new members, periodic reporting, gap review

### 🔬 Codebase analysis & evidence pipeline

Command | Purpose | When to use
--- | --- | ---
/code-analyzemaint | Analyze codebase → propose rules/contracts/architecture from real code | Bootstrap old codebases, or refresh after major changes
/evidence-ingestmaint | Pull raw data from MCP / API / paste / code into `evidence/sources/{id}/` | When external sources need to be ingested
/obsidian-ingestmaint | Batch ingest from Obsidian vault: scan, deduplicate, pre-check before ingest | Maintain your Obsidian Second Brain
/evidence-analyzemaint | Analyze ingested data | After ingestion
/evidence-qamaint | Q&A loop with user, generate `verified-facts.md` | After analysis, verify before apply
/evidence-applymaint | Apply verified facts to wiki | After verification

### 🔭 Pipeline observability

Command | Purpose | When to use
--- | --- | ---
/contextd-trace {run_id}maint | Render Markdown timeline 1 run pipeline (4 stage) | When `/use-contextd` output is wrong — debug stage divergence
/contextd-evalmaint | Metrics: hallucination rate, knowledge gaps, violation score | Periodic wiki quality check
/contextd-vizmaint | HTML viewer + live trace watch | Visual inspection

## 4Workflows that combine commands

Three real-world recipes — what becomes possible when commands chain together.

### 🚀 Bootstrap a legacy codebase in 30 minutes

Scenario: Inherit an undocumented codebase, need a wiki + shareable report for the team.

    /new-workspace acme-corp        # Create workspace shell
           ↓
    /code-analyze                    # Snapshot real code → propose rules & contracts
           ↓
    /evidence-qa                     # Verify proposed facts (Y/N per item)
           ↓
    /evidence-apply                  # Write verified facts into wiki
           ↓
    /contextd-report                 # Generate standalone HTML overview

Outcome: Wiki populated from real code + self-contained HTML report to share with the whole team. No more "where do I start?" for new hires.

### 🐛 Safe bug fix on Friday at 5pm

Scenario: Production duplicate-charge bug. You need a fix that respects your team's retry/idempotency rules — not what AI guesses.

    /find "idempotency retry"        # Locate the relevant pattern in seconds
           ↓
    /use-contextd "fix duplicate refund in payment flow"
           ↓     (planner → context → builder → reviewer — 4-stage pipeline)
       Claude writes code that follows the retrieved contract
           ↓
    /update-contextd                  # Sync changed code back into the wiki

Outcome: Fix that follows team rules, wiki stays in sync after merge — no drift between code and docs.

### 🔧 Solo builder: idea → running tool

Scenario: You're a domain expert (mechanical, accounting, healthcare, ...). You have an idea but don't know the tech stack.

    /tool-design "calculate steel beam bending moment"
           ↓     (6-8 guided questions, each with examples + "I don't know" option)
       Spec saved → workspaces/{ws}/tools/{slug}-spec.md
           ↓
    implement spec at workspaces/{ws}/tools/{slug}-spec.md
           ↓     (Claude implements faithfully — no stack drift)
    /tool-list                        # See your toolbox grouped by status
           ↓
    /tool-extend tool-name            # Add features later without rewriting

Outcome: A working tool + setup guide for Linux & Windows + a record in your toolbox.

## 5Available packs

Enable packs via `/contextd-setup` Step 4.5 (per-codebase checkbox UI, saved in `wiki.json#packs`) — or edit `workspaces/{ws}/workspace.md` under `## Packs` (workspace-wide default).

Pack | Status | Use for
--- | --- | ---
pack-event-driven | stable | Event processing: Kafka, MQTT, RabbitMQ — retries, DLQ handling
pack-web-api | stable | Web APIs: REST/GraphQL/gRPC — input validation, error shape, no information leakage
pack-frontend-react | stable | React + Next.js — hooks rules, a11y, effect cleanup, list keys, server/client boundary
pack-ui-ux | beta v0.1 | UI/UX design — design system, design tokens, WCAG 2.1 AA accessibility, user flows, UX writing. Pairs with `pack-frontend-react` (design doc ↔ code impl)
pack-ai-app | stable | AI apps: prompt caching, structured output, testing, privacy safety
pack-agentic | stable | AI agents: loops, tool use, multi-agent orchestration — bounded steps, safe retries
pack-claude-plugin-dev | stable | Claude Code plugin development — commands, subagents, skills, hooks
pack-product | beta | Product docs for PM/business — briefs, OKRs, roadmap, personas, metrics
pack-solo-builder | beta | For non-tech domain experts (mechanical, accounting, ...) using Claude Code as a "no-code IDE" — tool-design coach + cross-platform recipe library
pack-ba | beta | Business analysis — requirements modeling, acceptance criteria, process mapping, stakeholder alignment
pack-qc | beta v0.2 | Quality control + performance optimization (absorbs `pack-optimize`) — test design/execution, defect triage, regression, release gates, baseline metrics, profiling, regression guards
pack-security | beta v0.2 | Security engineering + authorized pentest (absorbs `pack-pentest`) — threat modeling, secure design reviews, scope discipline, evidence-based findings, risk rating, remediation
pack-dba | beta | DBA workflow — schema change safety, query hygiene, backup/restore readiness, operational guardrails

Example combinations: Solo fullstack → `pack-web-api + pack-frontend-react + pack-ai-app`. AI agent product → `pack-ai-app + pack-agentic + pack-web-api + pack-frontend-react`. Team with PMs → add `pack-product`.

## 6FAQ

I do not code — can I still use this wiki?

Yes — two paths depending on your role:

If you are PM/business in a team with engineers: enable `pack-product`, then use:

- `/product-brief` — create a new brief
- `/business-view {service}` — read service docs in business language
- `/contextd-explain topic` — explain technical terms

If you are a domain expert (mechanical, accounting, healthcare, ... ) building your own tools: enable `pack-solo-builder`, then use:

- `/tool-design "idea"` — wizard discovery + recommend tech stack
- `/tool-list` — view existing toolbox
- `/tool-extend tool-name` — extend an existing tool

You do not need git, terminal expertise, or coding. You only need to run commands in Claude Code.

I work across multiple companies/projects — can I use one wiki template?

Yes. Each company/project has its own workspace under `workspaces/{name}/`.

Create one: `/new-workspace project-name`. Switch one: `/switch-workspace name`.

Wiki and code drift — how do I sync?

Use two commands:

- `/update-contextd` — run after each merge
- `/rebase-contextd` — run regularly for a full check

Use `/contextd-eval` to see quality metrics and missing knowledge.

When should I use packs (and when not)?

Use packs for stack-specific knowledge (e.g. Kafka rules, React hooks rules). Enable via `/contextd-setup` Step 4.5.

Do NOT use packs for rules specific to your workspace — write them in `workspaces/{ws}/agents/constraints.md` with prefix `ws-`.

Engine-wide rules (all workspaces, stack-agnostic) belong in `agents/constraints.md`.

One workspace, multiple codebases, different pack needs — how?

Use per-codebase override via `.claude/wiki.json#packs`:

- Workspace default: `workspaces/acme-corp/workspace.md ## Packs` = `[pack-event-driven, pack-web-api]`
- Frontend codebase: `acme-frontend/.claude/wiki.json` sets `"packs": ["pack-frontend-react", "pack-web-api"]` → effective packs are frontend + web-api only
- Backend codebase (no override) → effective packs = workspace default

Replace semantics, not additive. `null`/missing field follows workspace default. Array fully overrides.

Easiest way: run `/contextd-setup` in the codebase → Step 4.5 shows all pack checkboxes and writes `wiki.json` automatically.

There are too many slash commands — do I need all of them?

No. Most people only need 3-4 commands:

- Daily engineering: `/use-contextd`, `/find`, `/update-contextd`
- Daily non-tech: `/product-brief`, `/business-view`, `/contextd-explain`
- One-time setup: `/contextd-setup` or `/new-workspace`

Learn the others only when you need them.

Where is my workspace stored?

Default path is `{wiki-template-root}/workspaces/{name}/`. You can override it with `wiki_root` in `~/.claude/wiki-global.json`. To see active path: use `/list-workspaces` or read `<cwd>/.claude/wiki.json`.

Can AI hallucinate knowledge not in the wiki?

The system enforces strict rules: if knowledge is missing, AI must report assumptions or constraint conflicts, not invent facts. A validator (`scripts/validate.py`) checks common violation patterns. For monitoring: `/contextd-eval` reports hallucination rate per run.

I want a new pack for a custom stack (e.g. Flutter) — how?

Run pack scaffold command:

    python scripts/scaffold-pack.py pack-mobile-flutter

This generates 8 skeleton files. Customize `pack.yaml` components + keywords, write `constraints.md`, and add rules in `scripts/rules.py`. Register it in catalog: edit `packs/README.md`.