FasalZein/wiki-forge

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.

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 and a later green step, preferably with one wiki forge tdd cycle command that shares the 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 cycle <project> <slice-id> --test tests/foo.test.ts --red-command "bun test tests/foo.test.ts" --green-command "bun test tests/foo.test.ts" --note "red failed before implementation; green passes after"

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 investigate -> plan -> build -> review/close. wiki forge plan is the single planning loop that can use grill-with-docs, PRD, and slice helpers without re-interviewing the user. 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 — grill-with-docs → PRD → slices → TDD, with wiki research as input)
                                          ↓
                                        You

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
./install.sh --wiki-only --skip-skills  # qmd only; install /wiki later if desired

The installer handles bun, dependencies, qmd/skill sync, shell config, and the vault directory (~/Knowledge). wiki-only installs just the second-brain layer (/wiki). full installs the second-brain layer plus the repo-owned Forge SDLC workflow stack. External optional skills such as research, prototype, and desloppify stay outside the repository and can be installed on demand.

Read next:

• SETUP.md — install, manual setup, Obsidian, troubleshooting, and copy/paste agent prompts
• How wiki-forge works — Wiki/QMD retrieval path and Forge next-command workflow
• Production Operator Guide — operating Forge on real project work
• Artifact Routing — where research, grill context, decisions, PRDs, slices, reviews, and handovers belong

For production operation, see Production Operator Guide.

Paste this into a new agent session after cloning the repo:

We are setting up wiki-forge. First read SETUP.md in full, then follow its install mode guidance. If I ask for wiki-only, install only the Wiki second-brain layer. If I ask for full setup, install Wiki plus the Forge workflow skills. Do not create project handover files in the repo; handovers belong in the Knowledge vault. After setup, run wiki qmd-status and tell me whether QMD needs embeddings.

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

bun run sync:local                                      # refresh qmd, reinstall repo-owned skills, and install configured external companions
bun run sync:link-cli                                   # explicitly relink the global wiki CLI to this checkout
bun run sync:local -- --install-set wiki-only           # refresh qmd and install only the wiki skill
bun run sync:local -- --install-set wiki-only --skip-skills # refresh qmd without installing agent skills
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 investigate -> plan -> build -> review/close
• full install gives you both layers
• wiki-only keeps the install in second-brain mode with no forge workflow stack

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

wiki scaffold-project my-app                              # create vault structure
wiki init my-app --repo ~/Dev/my-app                       # print repo/vault orientation + next commands
wiki onboard my-app --repo ~/Dev/my-app                    # scaffold + onboarding plan + root orientation sync
wiki onboard-plan my-app --repo ~/Dev/my-app --write      # generate onboarding plan
wiki sync my-app --repo ~/Dev/my-app --write               # refresh AGENTS.md / CLAUDE.md orientation files
wiki discover my-app --tree                                # find module candidates
wiki create-module my-app auth --source src/auth/          # create bound module spec

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 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

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

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

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 cycle my-app MY-APP-001 --test tests/foo.test.ts --red-command "bun test tests/foo.test.ts" --green-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:

1. wiki checkpoint = current freshness truth
2. wiki maintain = repair/reconciliation plan
3. wiki forge status <project> <slice> = workflow truth for one slice
4. 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

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

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 sync my-app --repo ~/Dev/my-app --json               # report missing/stale managed AGENTS.md / CLAUDE.md orientation 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.

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.

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.

Use this mental model:

• /wiki skill = knowledge/verification layer
• /forge skill = delivery workflow layer
• wiki CLI = shared command surface both skills rely on
• Wiki orientation = managed repo orientation block in AGENTS.md / CLAUDE.md
• Forge steering = wiki resume / wiki forge next / wiki forge status packets that tell agents which skill and phase to use

Compact map:

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

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.

Tracked implementation closes through Forge evidence and close gates:

wiki forge tdd cycle <project> <slice> --test <path> --red-command "<failing test command>" --green-command "<passing test 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.

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.

~/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

• 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

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

bun run sync:local            # refresh qmd, install repo-owned skills, and install configured external companions globally
bun run sync:link-cli         # explicitly relink the global wiki CLI to this checkout
bun run sync:local -- --audit # compare installed repo skills against the checked-out repo copies

Current repo-owned skill set:

• diagnose
• forge
• grill-with-docs
• handoff
• improve-codebase-architecture
• prd-to-slices
• tdd
• wiki
• write-a-prd

External optional skills:

• research for external investigation and evidence gathering
• prototype for throwaway logic/UI exploration
• desloppify for final code-quality scanning via npx skills add FasalZein/desloppify

These skills are not bundled into this repository. Use the installed external skill when available; do not re-add it to skills/ as a repo-owned skill.

Or install any individual skill from GitHub:

npx skills add FasalZein/desloppify
npx skills@latest add FasalZein/wiki-forge/skills/diagnose -g
npx skills@latest add FasalZein/wiki-forge/skills/forge -g
npx skills@latest add FasalZein/wiki-forge/skills/grill-with-docs -g
npx skills@latest add FasalZein/wiki-forge/skills/handoff -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/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.

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

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

investigate  ->  plan  ->  build  ->  review/close

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

# 2. Stress-test the plan against docs and code
/grill-with-docs

# 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

• 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.

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

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

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

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

bun test

MIT