GitHub - FasalZein/wiki-forge: Second-brain knowledge repository for humans and LLMs — compiled memory in markdown, not RAG

wiki-forge
Two layers: a second brain that remembers, and a forge that ships

Wiki — persistent, compounding knowledge maintained in markdown.
Forge — a software-development workflow that turns that knowledge into shipped code.
Agents handle the bookkeeping. You handle the thinking.

Runtime boundary

Wiki is the second-brain memory layer. Wiki manages durable memory artifacts across agents, sessions, and projects: research, notes, decisions, handovers, source bindings, durable context, and recall.

Forge is the SDLC lifecycle layer. Forge owns non-trivial feature implementation: feature → PRD → slice → implementation → TDD → verification → review → close/amend.

Kernel = truth; projections = help. Backlogs, status text, resume packets, handovers, and indexes support humans, but lifecycle decisions come from typed Forge kernel records, results, changesets, rejections, and evidence gates.

Explicit TDD = workflow proof. Forge does not infer TDD from a passing suite: record a failed red step, then a later green step with the exact same command and at least one same test path.

Targeted tests = slice proof; full suite = release gate. Normal slices run their targeted test plan plus bun run check; full bun test is reserved for explicit production release gates.

wiki forge next <project>
wiki forge status <project>
wiki forge plan <project> <feature-name> --repo <path>
wiki forge run <project> [slice-id] --repo <path>

TDD evidence is intentionally explicit and low-friction:

wiki forge tdd status <project> <slice-id> --json
wiki forge tdd red <project> <slice-id> --test tests/foo.test.ts --command "bun test tests/foo.test.ts" --note "expected failure before implementation"
wiki forge tdd green <project> <slice-id> --test tests/foo.test.ts --command "bun test tests/foo.test.ts" --note "same command now passes"

Not RAG. The wiki is a compiled artifact that grows over time, not a retrieval layer that re-derives answers from scratch each query. Code is always the source of truth — the wiki is compiled memory that makes code navigable across sessions. The conceptual delivery chain is wiki research -> /domain-model (+ /torpathy when design tradeoffs remain) -> /write-a-prd -> /prd-to-slices -> /tdd -> /desloppify. wiki forge plan|run|next is the compact operator surface over that chain, not a different workflow.

Sources (code, research, docs)
  ├── Wiki  (knowledge layer — maintained markdown in ~/Knowledge)
  └── Forge (workflow layer — domain-model → PRD → slices → TDD, with wiki research as input)
                                          ↓
                                        You

Quick Start

git clone https://github.com/FasalZein/wiki-forge.git
cd wiki-forge
./install.sh          # prompts for wiki-only vs full wiki+forge setup
# or:
./install.sh --wiki-only
./install.sh --full

The installer handles bun, dependencies, local sync of the CLI/qmd/skills, shell config, and the vault directory (~/Knowledge). wiki-only installs just the second-brain layer (/wiki). full installs the second-brain layer plus the forge SDLC workflow stack (/forge, the repo-owned workflow skills, and the external /desloppify companion). See SETUP.md for manual setup, Obsidian config, and troubleshooting. For production operation, see Production Operator Guide.

Manual prerequisites (if not using the installer)

bun run sync:local
brew install sqlite   # macOS — required for Bun SDK hybrid retrieval

Local Sync

bun run sync:local                                      # relink CLI, refresh qmd, reinstall repo-owned skills, and add external workflow companions
bun run sync:local -- --install-set wiki-only           # relink CLI/qmd and install only the wiki skill
bun run sync:local -- --audit                           # audit the default full repo-owned skill set
bun run sync:local -- --install-set wiki-only --audit   # audit only the wiki-only install set

Use this after pulling repo changes or editing skills/*/SKILL.md. Restart the agent session after syncing so it reloads the updated installed skills.

/wiki and /forge stay separate:

/wiki = second-brain layer: retrieval, maintenance, verification, filing, drift
/forge = SDLC layer over wiki research -> /domain-model -> /write-a-prd -> /prd-to-slices -> /tdd -> /desloppify
full install gives you both layers
wiki-only keeps the install in second-brain mode with no forge workflow stack

Features

Project Onboarding

Scaffold a project, discover its structure, and create module specs — all wired to the vault.

wiki scaffold-project my-app                              # create vault structure
wiki onboard my-app --repo ~/Dev/my-app                    # scaffold + onboarding plan + root protocol sync
wiki onboard-plan my-app --repo ~/Dev/my-app --write      # generate onboarding plan
wiki protocol sync my-app --repo ~/Dev/my-app              # sync AGENTS.md / CLAUDE.md (and nested scopes)
wiki discover my-app --tree                                # find module candidates
wiki create-module my-app auth --source src/auth/          # create bound module spec

Knowledge Maintenance

The core loop: code changes, the wiki updates, drift gets caught.

wiki maintain my-app --base main                           # default agent entry point
wiki refresh-from-git my-app --base main                   # map git changes -> impacted pages
wiki drift-check my-app --show-unbound                     # find stale + unbound pages
wiki ingest-diff my-app --base main                        # auto-append change digests
wiki verify-page my-app modules/auth/spec code-verified    # promote verification level
wiki bind my-app modules/auth/spec src/auth/               # replace source_paths
wiki bind my-app modules/auth/spec --mode merge src/new.ts # append normalized unique source_paths

Quality Gates

Quality checks run through lint, semantic lint, checkpoint/maintain, and Forge check/close gates.

wiki lint my-app                                           # structural: frontmatter, wikilinks, headings
wiki lint-semantic my-app                                  # semantic: orphans, dead-ends, placeholders
wiki doctor my-app                                         # health score (0-100) + prioritized actions
wiki forge check my-app <slice-id> --repo ~/Dev/my-app --base main    # workflow evidence/readiness check

Retrieval and Search

Intent-aware retrieval — BM25 for location queries, hybrid BM25+vector for rationale queries.

wiki search "auth middleware"                              # full-text search
wiki query "how does token refresh work"                   # intent-routed retrieval
wiki ask my-app "where is the rate limiter"                # compact project-scoped Q&A with citations
wiki ask my-app --verbose "where is the rate limiter"      # include routing + source sections
wiki file-answer my-app "how does caching work"            # save answer brief for compounding

Research Layer

File evidence, scaffold topics, ingest sources, and audit quality — all traceable in the vault.

wiki research file my-app "auth provider comparison"       # file a research note
wiki research scaffold "state management"                  # create topic container
wiki research ingest "state management" ./notes.md         # seed from existing findings
wiki research status                                       # coverage + health summary
wiki research lint                                         # check evidence freshness
wiki research audit                                        # influenced_by coverage + local deterministic link checks
wiki research audit --live-network                         # opt into public live URL validation
wiki source ingest https://example.com/article             # raw source -> raw/ + linked summary

Planning and Backlog

Features, PRDs, standalone planning docs, and vertical slices with task-scoped spec hubs — zero API calls.

Agent surface (3 commands):

# Plan: scaffold feature + PRD + slice + start
wiki forge plan my-app "user onboarding" --agent Codex --repo ~/Dev/my-app

# Run: auto-start + check + verify + close in one pass; writes progress to index.md
wiki forge run my-app --repo ~/Dev/my-app

# Next: pick the next slice
wiki forge next my-app

Agent rule: use wiki forge plan|run|next by default. Drop to wiki forge status, wiki checkpoint, or wiki maintain only for diagnosis, repair, or close-path debugging.

Internal / repair (debugging only):

wiki forge status my-app MY-APP-001 --repo ~/Dev/my-app
wiki forge tdd red my-app MY-APP-001 --test tests/foo.test.ts --command "bun test tests/foo.test.ts"
wiki forge tdd green my-app MY-APP-001 --test tests/foo.test.ts --command "bun test tests/foo.test.ts"
wiki forge evidence my-app MY-APP-001 verify --command "bun test ..."
wiki forge review record my-app MY-APP-001 --verdict approved --reviewer <name>
wiki resume my-app --repo ~/Dev/my-app --base main
wiki export-prompt my-app MY-APP-001 --agent pi

When outputs disagree, use this authority order:

wiki checkpoint = current freshness truth
wiki maintain = repair/reconciliation plan
wiki forge status <project> <slice> = workflow truth for one slice
wiki resume = contextual summary only

Practical debugging rule:

prefer wiki forge status <project> <slice> over project-level status when diagnosing one slice
if checkpoint is clean, do not treat noisy resume stale context as a current blocker
if a generated page like projects/<project>/_summary.md is stale, prefer wiki sync / wiki maintain before manual edits

Use depends_on in slice frontmatter to block a slice until prerequisite slices move to Done:

depends_on:
  - MY-APP-001

Agent Coordination

wiki handover my-app --repo ~/Dev/my-app --base main      # backlog + git + dirty state handoff
wiki note my-app "left off at parser" --slice MY-APP-001 # durable agent-to-agent note in log.md

Automation and CI

wiki commit-check my-app --repo ~/Dev/my-app              # staged-file freshness check for local commits
wiki checkpoint my-app --repo ~/Dev/my-app                # git-independent freshness check against current worktree mtimes
wiki lint-repo my-app --repo ~/Dev/my-app                 # flag ad hoc repo markdown outside the allowed set
wiki protocol audit my-app --repo ~/Dev/my-app            # detect missing/stale managed AGENTS.md / CLAUDE.md files
wiki install-git-hook my-app --repo ~/Dev/my-app          # writes a pre-commit hook that runs commit-check
wiki refresh-on-merge my-app --repo ~/Dev/my-app --base main --verbose
wiki dependency-graph my-app --write                       # writes verification/dependency-graph.canvas

Use --verbose when you want expanded human-readable detail. Keep default text output compact, and prefer --json for CI or agent chaining.

Navigation and Index

wiki summary my-app                                        # one-shot project overview
wiki update-index my-app --write                           # regenerate spec indexes + derived relationship sections
wiki log                                                   # chronological operation log

update-index refreshes feature/PRD/slice lineage sections, module/freeform-zone planning links from source_paths, and the generated spec family indexes.

Obsidian Integration

The vault is a native Obsidian vault — wikilinks, graph view, backlinks, embeds, callouts, and properties work out of the box.

wiki obsidian open modules/auth/spec                       # open in Obsidian (requires CLI enabled)
wiki obsidian backlinks modules/auth/spec                  # show backlinks
wiki obsidian orphans                                      # find orphan notes

Enable the CLI: Obsidian 1.8+ -> Settings -> General -> CLI. See SETUP.md.

How It Works

Command Taxonomy

Use this mental model:

/wiki skill = knowledge/verification layer
/forge skill = delivery workflow layer
wiki CLI = shared command surface both skills rely on
Agent Protocol = managed repo instruction block in AGENTS.md / CLAUDE.md
Wiki Protocol = mandatory wiki ... command sequence inside that agent protocol

Compact map:

Area	Main commands
Protocol	`wiki protocol sync`, `wiki protocol audit`
Planning	`wiki forge plan`, `wiki forge next`, `wiki forge status`
Hierarchy/admin views	`wiki feature-status`, `wiki update-index`, `wiki dependency-graph`
Lifecycle	`wiki forge plan/run/next/start/check/close/status/release/evidence/review`
Active work checks	`wiki checkpoint`, `wiki lint-repo`, `wiki commit-check`
Verification	`wiki verify-page`, `wiki forge evidence`, `wiki forge check`, `wiki forge close`
Handoff	`wiki export-prompt`, `wiki resume`, `wiki handover`, `wiki note`
Maintenance / retrieval	`wiki maintain`, `wiki refresh-from-git`, `wiki drift-check`, `wiki ask`, `wiki query`, `wiki search`

The Three Layers

Layer	What it is	Who owns it
Wiki	Maintained project memory in `~/Knowledge`	`wiki` CLI
Research	Filed evidence and source-backed notes under `research/` and `raw/`	`/research` skill + `wiki research` commands
Forge	Optional workflow layer over `wiki research -> /domain-model -> /write-a-prd -> /prd-to-slices -> /tdd -> /desloppify`; agent surface is `wiki forge plan/run/next`	`/forge` skill

These are separate concerns. The wiki is the knowledge store. Research is evidence. Forge is the software-development workflow layer over that memory.

Verification Levels

Every wiki page has a verification level that tracks how current it is:

scaffold  ->  inferred  ->  code-verified  ->  runtime-verified  ->  test-verified

When source code changes after verification, drift-check demotes the page to stale. Stale pages get flagged, not trusted.

Mandatory Close Sequence

Tracked implementation closes through Forge evidence and close gates:

wiki forge tdd red <project> <slice> --test <path> --command "<failing test command>"
wiki forge tdd green <project> <slice> --test <same path> --command "<same command>"
wiki forge evidence <project> <slice> verify --command "<targeted command>"
wiki forge review record <project> <slice> --verdict approved --reviewer <name>
wiki forge run <project> <slice> --repo <path>

Wiki freshness remains a separate maintenance concern handled by wiki checkpoint, wiki maintain, and wiki verify-page.

Trigger Phrases

These phrases route to the closeout sequence above:

"wiki refresh" / "wiki maintain"
"update project wiki"
"refresh project docs from code"
"close out this slice"
"run wiki maintenance"

Disambiguation: Avoid "refresh memory" (clashes with Claude Code auto-memory), "sync docs" (ambiguous with Notion/Confluence), or bare "update wiki" (ambiguous with GitHub wiki). Always include "wiki", "project", or "slice" for clear routing.

Vault Layout

~/Knowledge/
  index.md                            # vault entry point
  log.md                              # chronological operation log
  projects/<name>/
    _summary.md                       # project config (repo, code_paths)
    backlog.md                        # task tracking
    decisions.md                      # decision log
    learnings.md                      # lessons learned
    modules/<mod>/spec.md             # module documentation
    forge/
      sessions/                       # planning-session state
      features/                       # Forge feature records
      prds/                           # Forge PRD/spec records
      slices/<TASK-ID>/               # slice hub + plan + test-plan
      evidence/                       # typed TDD/verification/review evidence
      handovers/                      # typed handover memory
  research/                           # research artifacts
  raw/                                # ingested raw sources
  wiki/syntheses/                     # filed answer briefs

Project Zones

modules/ — runtime/code ownership. What code exists, what it owns, and how it is verified.
architecture/ — cross-module topology, boundaries, and high-level design maps.
code-map/ — repo/package/service maps, entrypoints, and where behavior lives.
contracts/ — APIs, events, schemas, and external/internal interface surfaces.
data/ — tables, entities, migrations, invariants, and relationships.
changes/ — rollouts, migrations, change plans, and notable implementation deltas.
runbooks/ — operational procedures, incident handling, and recurring manual workflows.
verification/ — coverage, test strategy, runtime checks, and closeout evidence.
legacy/ — old docs kept as source material, not canonical truth.
forge/features/ — product/planning scopes.
forge/prds/ — numbered requirement docs under one parent feature.
forge/slices/ — execution slices under an optional parent PRD.

Propagation rule:

planning lineage (feature -> PRD -> slice) comes from metadata (feature_id, prd_id, parent_feature, parent_prd)
wiki forge plan creates or updates Forge-owned feature, PRD, slice, and test-plan records.
module/freeform-zone linkage comes from source_paths overlap
wiki update-index <project> --write regenerates those derived sections across spec pages, modules, and freeform project zones

Skills

Repo-owned skills are installed via the local sync script and auto-discovered from skills/*/SKILL.md:

bun run sync:local            # relink CLI, refresh qmd, install repo-owned skills, and add external workflow companions globally
bun run sync:local -- --audit # compare installed repo skills against the checked-out repo copies

Current repo-owned skill set:

domain-model
forge
grill-me (optional compatibility skill; forge now routes through domain-model)
improve-codebase-architecture
prd-to-slices
research
tdd
wiki
write-a-prd

External workflow companion:

desloppify via npx skills add FasalZein/desloppify

Or install any individual skill from GitHub:

npx skills add FasalZein/desloppify
npx skills@latest add FasalZein/wiki-forge/skills/domain-model -g
npx skills@latest add FasalZein/wiki-forge/skills/forge -g
npx skills@latest add FasalZein/wiki-forge/skills/grill-me -g
npx skills@latest add FasalZein/wiki-forge/skills/improve-codebase-architecture -g
npx skills@latest add FasalZein/wiki-forge/skills/prd-to-slices -g
npx skills@latest add FasalZein/wiki-forge/skills/research -g
npx skills@latest add FasalZein/wiki-forge/skills/tdd -g
npx skills@latest add FasalZein/wiki-forge/skills/wiki -g
npx skills@latest add FasalZein/wiki-forge/skills/write-a-prd -g

sync:local is the canonical path because it keeps the installed skill copies aligned with the checked-out repo. Restart the agent session after syncing so it reloads the refreshed instructions.

Skill Reference

Skill	Invoke	What it does	When to use
research	`/research`	Investigates external evidence and produces research artifacts that can be filed into the wiki	When a feature, refactor, or architecture decision needs outside evidence
wiki	`/wiki`	Knowledge-layer operations: research, retrieval, maintenance, drift, verification, gates	When no non-trivial product behavior is being planned or changed
forge	`/forge`	Software-development workflow over `wiki research -> /domain-model -> /write-a-prd -> /prd-to-slices -> /tdd -> /desloppify`	Non-trivial implementation work, new features, cross-module changes, or existing slice continuation
prd-to-slices	`/prd-to-slices`	Breaks a PRD/spec into Forge-planned vertical slices	After writing a PRD/spec, before implementation
write-a-prd	`/write-a-prd`	Drafts PRD/spec content for `wiki forge plan`	When you need formal project intent
domain-model	`/domain-model`	Sharpens terms, records decisions in the wiki, and surfaces ambiguities before PRD authoring	Before writing a PRD
tdd	`/tdd`	Red-green-refactor with vertical slices — no code without tests, ever	During implementation
improve-codebase-architecture	`/improve-codebase-architecture`	Finds deeper-module and boundary-refactor candidates and turns them into tracked follow-up work	At cadence boundaries or after shipping a batch
desloppify	`/desloppify`	Scans for AI-introduced anti-patterns, triages, fixes, verifies	Final quality gate after Forge close
grill-me	`/grill-me`	Optional interview-style stress test for a plan when you explicitly want adversarial questioning	Compatibility path outside the main forge happy path

When to Use What

Task	Workflow
Knowledge maintenance / verification / retrieval	`/wiki`
Research-only work	`/wiki` + `/research` when external investigation is needed
Research capture	`/research` + `wiki research file`
Small code fix (< 50 lines)	`/tdd` + `/wiki` + `/desloppify`
Wiki / note cleanup	`/wiki` + `/obsidian-markdown`
Repo exploration	`wiki maintain`
New feature, workflow, or cross-module change	`/forge` (full pipeline)
Continue an existing PRD/slice thread	`/forge`

Wiki vs Forge

Assume a skill-capable harness can use both. The real question is which layer the task belongs to.

Use /wiki for:

research filing, audit, and status
retrieval and project Q&A
refresh, drift, verify, lint, checkpoint, and maintain
wiki formatting, vault cleanup, onboarding, and navigation
research-only work that does not yet commit to implementation

Use /forge for:

non-trivial implementation work
new features and workflows
cross-module changes
performance/refactor work with tradeoffs
existing PRD/slice continuation
research when it is phase 1 of a larger implementation effort

Rule of thumb:

changing product/runtime behavior -> /forge
researching, retrieving, documenting, or verifying without active product changes -> /wiki

Forge Workflow

For non-trivial work, forge orchestrates the full pipeline:

wiki research  ->  /domain-model (+ /torpathy when needed)  ->  /write-a-prd  ->  /prd-to-slices  ->  /tdd  ->  /desloppify

# 1. Investigate
/research "topic title"
wiki research file my-app "topic title"

# 2. Stress-test the plan
/domain-model

# 3. Create the parent feature + PRD
wiki forge plan my-app "feature name" --repo ~/Dev/my-app

# 4. Break into slices
wiki forge plan my-app "feature name" --repo ~/Dev/my-app

# 5. Implement (TDD)
# write tests first, then implement, then refactor — no exceptions

# 6. Close through Forge
wiki forge evidence my-app <slice-id> verify --command "bun test ..."
wiki forge run my-app <slice-id> --repo ~/Dev/my-app

# 7. Quality gate (final step)
desloppify scan .        # detect AI-introduced anti-patterns
desloppify score .       # verify no regression

Guardrails

Wiki vault is the knowledge store. Agents write documentation to ~/Knowledge, not to project repos.
Code is the source of truth. Wiki pages compile from code, never the other way around.
No wiki-style docs in project repos. Architecture docs, module specs, research — all go to the vault. Allowed repo markdown: README.md, CHANGELOG.md, AGENTS.md, CLAUDE.md, SETUP.md, and skills/*/SKILL.md.
Verification prevents drift. Every page has a verification level. drift-check demotes stale pages when source code changes.
No code without tests. TDD is non-negotiable — Forge evidence/check/close gates require test proof before completion.
Desloppify is the final gate. Every workflow ends with a desloppify scan to catch AI-introduced anti-patterns before declaring done.

Obsidian

The vault is a first-class Obsidian vault. Recommended companion skills for agents editing vault docs:

Skill	When to use
`obsidian-markdown`	Default for vault markdown — properties, wikilinks, embeds, callouts
`obsidian-cli`	Only when operating a running Obsidian app from the terminal
`json-canvas`	Derived relationship maps — never as canonical state
`obsidian-bases`	Derived dashboards/views — never as canonical state

Start with obsidian-markdown. The others complement the UI layer but markdown/frontmatter is the canonical contract.

Retrieval Architecture

The CLI uses qmd for indexing and retrieval:

BM25 SDK path for location and general queries (fast, ~40ms warm)
Hybrid SDK path (BM25 + vector, pre-expanded, no rerank) for rationale queries (~45ms warm)
qmd SDK + Bun wrapper now back the admin/indexing flow too (qmd-setup, qmd-update, qmd-embed, qmd-status), so wiki-forge no longer depends on a separately working global qmd CLI for maintenance
slice workflow now supports assignees, prompt export, resume views, backlog filtering, and structural-refactor gate exceptions for clean handoffs across Codex, Claude, and pi

wiki qmd-update          # re-index vault
wiki qmd-embed           # generate embeddings
wiki qmd-status          # index health

Benchmarking

Use an isolated index to avoid polluting your main state:

QMD_INDEX_NAME=wiki-bench bun src/index.ts qmd-setup
bun run bench:qmd
# bench:qmd uses scripts/qmd-cli.ts so Bun loads Homebrew SQLite before qmd CLI startup

The harness measures BM25, vector, expand-query, and structured variants plus cold/warm latency for wiki query and wiki ask.

Testing

bun test

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 356 Commits
architecture		architecture
bin		bin
docs		docs
experiments/ax-optimizer		experiments/ax-optimizer
schemas		schemas
scripts		scripts
skills		skills
src		src
tests		tests
.desloppifyignore		.desloppifyignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
SETUP.md		SETUP.md
bun.lock		bun.lock
eslint.config.js		eslint.config.js
fallow.json		fallow.json
install.sh		install.sh
knip.jsonc		knip.jsonc
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Runtime boundary

Quick Start

Local Sync

Features

Project Onboarding

Knowledge Maintenance

Quality Gates

Retrieval and Search

Research Layer

Planning and Backlog

Agent Coordination

Automation and CI

Navigation and Index

Obsidian Integration

How It Works

Command Taxonomy

The Three Layers

Verification Levels

Mandatory Close Sequence

Trigger Phrases

Vault Layout

Project Zones

Skills

Skill Reference

When to Use What

Wiki vs Forge

Forge Workflow

Guardrails

Obsidian

Retrieval Architecture

Testing

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages