wiki-bfs

/wiki-bfs — Breadth-First Research + Wiki Ingest

Usage

/wiki-bfs <topic> [--layers N] [--ingest] [--wiki <wiki_dir>]

Performs N-layer breadth-first search on a topic, discovers entities and concepts, creates wiki pages, and optionally triggers wiki-assess.

Default: 2 layers. Use --layers N for N layers.

--wiki <wiki_dir> overrides the default wiki location (~/llm_wiki/wiki). The raw/ directory is derived as $(dirname <wiki_dir>)/raw.

Execution

Phase 1: Parse arguments

• TOPIC = first positional arg (required)
• N = from --layers N flag, default 2
• INGEST = present if --ingest flag set
• WIKI = from --wiki <path> flag, default $HOME/llm_wiki/wiki

Phase 2: Resolve wiki path

# Check for local wiki default (project-level override)
if [ -f ".wiki-default" ]; then
  WIKI=$(cat .wiki-default)
elif [ -f "$HOME/.wiki-default" ]; then
  WIKI=$(cat "$HOME/.wiki-default")
else
  WIKI="$HOME/llm_wiki/wiki"
fi
# --wiki flag always wins over .wiki-default
if args contain "--wiki <path>"; then
  WIKI="<path>"
fi
mkdir -p "$WIKI/entities" "$WIKI/concepts" "$WIKI/sources"

Phase 3: BFS Research (N layers)

Launch parallel research agents per layer. Each layer discovers new topics that become the next layer's research targets.

Layer architecture:

Layer 0 (seed): <TOPIC>
Layer 1: Explore <TOPIC>'s primary systems/frameworks/people
Layer 2: Explore Layer 1's supporting infrastructure, alternatives, critics
Layer N: Explore Layer N-1's ecosystem, downstream, upstream

Research areas per topic (auto-detected):

• Governance/constraints/policy → research: governance patterns, fail-closed systems, policy engines
• multi-agent/agent coordination → research: orchestration frameworks, evidence systems, workflow engines
• coding agents/SWE → research: benchmarks, verification, skill libraries
• workflow/durability → research: workflow engines, event sourcing, execution models

For each layer:

1. Search web for the topic's canonical projects, papers, people
2. Fetch accessible pages (arxiv, github readmes, official docs)
3. Extract entity names (people, companies, projects) and concept names (patterns, methods, architectures)
4. Compile findings into structured report

Phase 4: Deduplicate against existing wiki

# Check which entities already exist
for entity in "${ENTITIES[@]}"; do
  slug=$(echo "$entity" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  if [ -f "$WIKI/entities/$slug.md" ]; then
    echo "EXISTS: $entity"
  else
    echo "NEW: $entity"
  fi
done

# Check which concepts already exist
for concept in "${CONCEPTS[@]}"; do
  slug=$(echo "$concept" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  if [ -f "$WIKI/concepts/$slug.md" ]; then
    echo "EXISTS: $concept"
  else
    echo "NEW: $concept"
  fi
done

Phase 5: Create wiki pages

Entity page template:

---
title: "<EntityName>"
type: entity
tags: [<topic-area>, <type>]
date: YYYY-MM-DD
---

## Overview
2–3 sentence overview.

## Key Properties
- **Type**: 
- **Key features**: 

## Connections
- [[RelatedConcept]] — relationship
- [[RelatedEntity]] — relationship

## See Also
- [[RelatedConcept]]

Concept page template:

---
title: "<ConceptName>"
type: concept
tags: [<topic-area>, <pattern-type>]
date: YYYY-MM-DD
---

## Overview
2–3 sentence overview.

## Key Properties
- **What**: 
- **Why matters**: 

## Related Systems
| System | Type | Relevance |
|--------|------|-----------|

## Connection to <TOPIC>
How this concept relates to the BFS root topic.

## See Also
- [[RelatedEntity]]
- [[RelatedConcept]]

Phase 6: Update index

Add new entities and concepts to wiki/index.md under appropriate sections with brief descriptions.

Phase 7: Log

Append to wiki/log.md: ## [YYYY-MM-DD] bfs | <TOPIC> — <N> layers, <X> new entities, <Y> new concepts

Phase 8: (Optional) wiki-assess

If --ingest flag is set, run wiki-assess after all pages created.

BFS Layer Routing

Topic keywords	Layer 1 research areas	Layer 2 research areas
governance, constraint, fail-closed	policy engines, constitutional AI, OPA, GitOps	stream governance, RBAC, drift detection, value alignment
multi-agent, orchestration, coordination	LangGraph, AutoGen, CrewAI, MetaGPT	CAMEL, router-architecture, prompt registry, multi-turn alignment
coding agent, SWE, evidence	SWE-bench, OpenHands, Voyager, Devin	AgentBench, skill library, self-verification, iterative prompting
workflow, durability, execution	Temporal, Prefect, Archon, Airbyte	event sourcing, durable execution, MCP Server, YAML DAGs
policy, ACL, authorization	OPA, Rego, Constitutional AI, RLAIF	CIRL, value alignment, scalable oversight, constitutional classifiers

Research Output Format

Each layer agent returns:

## Entities discovered
- EntityName: type, key properties, source

## Concepts discovered
- ConceptName: definition, key properties, source

## Key quotes
> "Quote" — source

## New topics for next layer
- NextTopicName (reason: discovered in this layer)

Quality Standards

• All entities must have ≥2 factual properties (not just "exists")
• All concepts must connect to ≥2 existing wiki pages
• Key quotes must include attribution and date
• Frontmatter must have title, type, tags, date