contextd — 5-Minute Onboarding (Claude Code)

📖 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-workspacesnontechtech	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.