Extract comprehensive semantic knowledge from a codebase to enable intelligent coding context, architectural guardrails, and constraint enforcement.
Extracts comprehensive semantic knowledge from codebases to enable intelligent coding context and architectural guardrails.
/plugin marketplace add jingnanzhou/fellow/plugin install jingnanzhou-fellow@jingnanzhou/fellowExtract comprehensive semantic knowledge from a codebase to enable intelligent coding context, architectural guardrails, and constraint enforcement.
Supports Incremental Updates: Only re-analyzes changed files for fast updates during active development.
Analyze a target project and extract three types of knowledge:
Store this knowledge in the target project's .fellow-data/semantic/ directory for use by coding assistants.
Project Path (optional): Path to target project
Mode Flags (optional):
--full: Force complete re-extraction (ignore existing KB)--update: Force incremental update (default if KB exists)When: No knowledge base exists OR --full flag used
Time: 2-5 minutes for medium project
Process: Analyzes entire codebase from scratch
When: Knowledge base exists AND (no flag OR --update flag)
Time: 5-30 seconds for typical changes (1-10 files)
Process:
Goal: Determine extraction mode (full vs incremental)
Actions:
.fellow-data/semantic/ existsextraction_metadata.json--full or --update--full flag--update flag)Mode: Incremental Update (3 files changed since last extraction)
or
Mode: Full Extraction (initial build)
Goal: Determine target project path and validate it exists
Actions:
realpath or Python's os.path.abspath()
realpath <target-path> or python3 -c "import os; print(os.path.abspath('<target-path>'))"TARGET_ABSOLUTE_PATH - this will be used in all agent promptsmkdir -p ${TARGET_ABSOLUTE_PATH}/.fellow-data/semantic/Important: The TARGET_ABSOLUTE_PATH variable must be used in all subsequent phases when launching agents or writing files. Never use relative paths.
Goal: Identify files that changed since last extraction
CRITICAL: This is an EXECUTABLE phase. You MUST run the change detection tool, not execute git commands manually.
Actions:
Run the change detection tool:
python3 ${CLAUDE_PLUGIN_ROOT}/tools/detect_changes.py <target-path>
What the tool does:
.fellow-data/semantic/extraction_metadata.jsonExpected Output (Changes Detected):
๐ Detecting changes using git...
๐ Files Changed Since Last Extraction:
๐ Modified (2 files):
โข src/services/auth.py
โข src/api/routes.py
โจ New (1 files):
โข src/services/notification.py
๐๏ธ Deleted (1 files):
โข src/utils/deprecated.py
๐ Total: 4 files to re-analyze
๐ Detection method: git
๐ JSON Output:
{
"status": "success",
"mode": "incremental",
"modified": ["src/services/auth.py", "src/api/routes.py"],
"new": ["src/services/notification.py"],
"deleted": ["src/utils/deprecated.py"],
"total": 4,
"detection_method": "git"
}
Expected Output (No Changes):
โ
Knowledge base is up-to-date
No files changed since last extraction
Detection method: git
๐ก Tip: Make code changes and run /fellow:build-kb again to update
Important:
<target-path> with the absolute path to the target projectmode is "up_to_date", skip extraction and exit earlyGoal: Extract all three types of knowledge (full or incremental based on mode)
CRITICAL REQUIREMENTS:
TARGET_ABSOLUTE_PATH from Phase 1) in all agent prompts<target-path> in agent prompts/Users/jingnan.zhou/workspace/my-project) not placeholdersExample: If the target project is at /Users/jingnan.zhou/workspace/my-project, the agent prompt should contain:
When: No existing KB OR --full flag
Actions:
CRITICAL: Use the TARGET_ABSOLUTE_PATH from Phase 1 in all agent prompts below. Replace the placeholder <target-path> with the actual absolute path.
Launch three extraction agents simultaneously:
Agent 1: factual-knowledge-extractor
Agent 2: procedural-knowledge-extractor
Agent 3: conceptual-knowledge-extractor
Wait for all three agents to complete
Verify all three JSON files were created successfully by checking if they exist:
${TARGET_ABSOLUTE_PATH}/.fellow-data/semantic/factual_knowledge.json${TARGET_ABSOLUTE_PATH}/.fellow-data/semantic/procedural_knowledge.json${TARGET_ABSOLUTE_PATH}/.fellow-data/semantic/conceptual_knowledge.jsonWhen: KB exists AND (no flag OR --update flag) AND files changed
Actions:
CRITICAL: Use the TARGET_ABSOLUTE_PATH from Phase 1 in all agent prompts below. Replace the placeholder <target-path> with the actual absolute path.
Launch three extraction agents with file-specific prompts:
Agent 1: factual-knowledge-extractor (targeted)
Agent 2: procedural-knowledge-extractor (targeted)
Agent 3: conceptual-knowledge-extractor (light analysis)
Wait for all agents to complete
Verify delta files were created successfully by checking if they exist
Delta Files (Temporary):
factual_knowledge_delta.json - Entities from changed files onlyprocedural_knowledge_delta.json - Workflows from changed files onlyconceptual_knowledge_delta.json - Architectural updates (if any)Goal: Merge extracted delta knowledge with existing knowledge base
CRITICAL: This is an EXECUTABLE phase. You MUST run the merge tool, not display implementation details.
Actions:
Run the knowledge merge tool:
python3 ${CLAUDE_PLUGIN_ROOT}/tools/merge_knowledge.py <target-path>
What the tool does:
Expected Output:
๐ฆ Loading existing knowledge base...
๐ฆ Loading delta knowledge...
๐ Merging knowledge for 3 changed files...
๐พ Writing merged knowledge base...
๐งน Cleaning up delta files...
โ
Knowledge Base Updated (Incremental)
๐ Merge Statistics:
Factual Knowledge:
โข Entities removed: 3 (from changed files)
โข Entities added: 5 (new extraction)
โข Relationships updated: 8
Procedural Knowledge:
โข Workflows updated: 2
โข Workflows added: 1
Conceptual Knowledge:
โข Status: No architectural changes
๐ Knowledge base location: /path/to/project/.fellow-data/semantic/
Important:
<target-path> with the absolute path to the target projectextraction_metadata.jsonGoal: Ensure extraction succeeded and gather statistics
Actions:
Check that all three JSON files exist:
<target-path>/.fellow-data/semantic/factual_knowledge.json<target-path>/.fellow-data/semantic/procedural_knowledge.json<target-path>/.fellow-data/semantic/conceptual_knowledge.jsonRead each file and extract summary statistics:
Goal: Create comprehensive markdown documentation for human readers
Actions:
Read all three JSON files:
Generate comprehensive markdown summary including:
Write to <target-path>/.fellow-data/semantic/SEMANTIC_KNOWLEDGE_SUMMARY.md
Goal: Track extraction state for future incremental updates
Actions:
Collect File Information:
# For each source file analyzed
file_registry = {}
for file_path in analyzed_files:
file_registry[file_path] = {
"last_analyzed": current_timestamp(),
"hash": calculate_sha256(file_path),
"size": get_file_size(file_path),
"entities_extracted": get_entities_from_file(file_path),
"workflows_extracted": get_workflows_from_file(file_path),
"status": "analyzed"
}
Collect Git Information (if available):
Run the git info tool:
python3 ${CLAUDE_PLUGIN_ROOT}/tools/git_info.py <target-path>
This collects:
Create Metadata Structure:
{
"version": "2.0.0",
"project_path": "/absolute/path/to/project",
"last_full_extraction": "2026-01-05T10:00:00Z",
"last_update": "2026-01-05T10:00:00Z",
"extraction_method": "full",
"git_info": {
"commit_hash": "abc123def456",
"branch": "main",
"has_uncommitted_changes": false
},
"file_registry": {
"src/main.py": {
"last_analyzed": "2026-01-05T10:00:00Z",
"hash": "sha256:abc123...",
"size": 1234,
"entities_extracted": ["MainClass"],
"workflows_extracted": ["startup"],
"status": "analyzed"
}
},
"statistics": {
"total_files_analyzed": 25,
"total_entities": 45,
"total_workflows": 12,
"extraction_duration_seconds": 180
}
}
Write Metadata File:
<target-path>/.fellow-data/semantic/extraction_metadata.jsonUpdate on Incremental:
# For incremental updates
metadata["last_update"] = current_timestamp()
metadata["extraction_method"] = "incremental"
metadata["git_info"]["commit_hash"] = new_commit_hash
# Update file registry for changed files
for changed_file in changed_files:
metadata["file_registry"][changed_file] = {
"last_analyzed": current_timestamp(),
"hash": new_hash,
...
}
# Update statistics
metadata["statistics"]["files_changed_since_last_update"] = len(changed_files)
metadata["statistics"]["entities_added"] = entities_added
metadata["statistics"]["entities_removed"] = entities_removed
Goal: Inform user of successful extraction
For Full Extraction:
โ Knowledge base built successfully!
Mode: Full Extraction
Target Project: /path/to/project
Extracted Knowledge:
- Factual: 45 entities, 67 relationships
- Procedural: 12 workflows, 8 patterns
- Conceptual: 4 layers, 9 modules, 10 design patterns
Output Location: /path/to/project/.fellow-data/semantic/
Files Created:
- factual_knowledge.json (machine-readable entities)
- procedural_knowledge.json (machine-readable workflows)
- conceptual_knowledge.json (machine-readable architecture)
- SEMANTIC_KNOWLEDGE_SUMMARY.md (human-readable comprehensive summary)
- extraction_metadata.json (tracks extraction state)
Time: 3 minutes 15 seconds
Next: Use `/build-kb` to update after code changes (incremental)
For Incremental Update:
โ Knowledge base updated successfully!
Mode: Incremental Update
Target Project: /path/to/project
Files Changed: 4 files
- Modified: src/services/auth.py, src/api/routes.py
- New: src/services/notification.py
- Deleted: src/utils/deprecated.py
Knowledge Updates:
- Factual: 3 entities removed, 5 entities added, 8 relationships updated
- Procedural: 2 workflows updated, 1 workflow added
- Conceptual: No architectural changes
Output Location: /path/to/project/.fellow-data/semantic/
Files Updated:
- factual_knowledge.json (updated)
- procedural_knowledge.json (updated)
- conceptual_knowledge.json (unchanged)
- SEMANTIC_KNOWLEDGE_SUMMARY.md (regenerated)
- extraction_metadata.json (updated)
Time: 15 seconds (12x faster than full extraction)
Tip: Use `/build-kb --full` to force complete re-extraction if needed
For No Changes:
โ Knowledge base is up-to-date
Mode: Incremental Update Check
Target Project: /path/to/project
No files changed since last extraction
Last extracted: 2026-01-05T10:00:00Z (2 hours ago)
Knowledge base location: /path/to/project/.fellow-data/semantic/
Tip: Make code changes and run `/build-kb` again to update
Mark all todos complete.
Goal: Ensure .fellow-data/ is excluded from git
Actions:
Check if target project is a git repository:
cd <target-path>
if [ -d .git ]; then
# It's a git repo
fi
If git repository, ensure .fellow-data/ is in .gitignore:
python3 ${CLAUDE_PLUGIN_ROOT}/hooks/gitignore_helper.py <target-path>
The helper script will:
.gitignore exists.fellow-data/ is already present.gitignore doesn't exist, create itOutput:
โ Added .fellow-data/ to .gitignore
Or:
โน๏ธ .fellow-data/ already in .gitignore
Or:
โน๏ธ Not a git repository - skipping .gitignore update
Rationale:
.fellow-data/ contains generated files (knowledge base, logs)Note: This is a courtesy feature. If the script fails, don't block the build-kb command.
If any agent fails:
# Build KB for current project (first time - full extraction)
/build-kb
# Build KB for specific project
/build-kb /path/to/other/project
# Build KB for relative path
/build-kb ../my-project
# After making code changes (auto-detects incremental mode)
/build-kb
# Explicitly request incremental update
/build-kb --update
# Force full rebuild even if KB exists
/build-kb --full
# Day 1: Initial setup
cd /path/to/my-project
/build-kb
# Output: Full extraction (3 minutes)
# Day 2: After changing 3 files
/build-kb
# Output: Incremental update (15 seconds)
# - Detected 3 changed files
# - Updated entities and workflows
# Week 2: After major refactoring
/build-kb --full
# Output: Full re-extraction (3 minutes)
# - Ensures KB is fully consistent
# Team member A: Makes changes and updates KB
git pull
# ... make changes to code ...
/build-kb # Incremental update
git add .fellow-data/semantic/
git commit -m "feat: Add notification service + update KB"
git push
# Team member B: Pulls changes
git pull
# KB is already up-to-date!
# Can immediately use /fellow command
Full Extraction: 2-5 minutes for medium project (10K-50K LOC)
Incremental Update: 5-30 seconds for typical changes (1-10 files)
Generates 5 files in .fellow-data/semantic/:
factual_knowledge.json - Machine-readable entities (Step 2 of Fellow plugin)procedural_knowledge.json - Machine-readable workflows (Step 2 of Fellow plugin)conceptual_knowledge.json - Machine-readable architecture (Step 2 of Fellow plugin)SEMANTIC_KNOWLEDGE_SUMMARY.md - Human-readable documentationextraction_metadata.json - Tracks extraction state for incremental updates โญ NEW/build-kb/build-kb after code changes (auto-incremental).fellow-data/semantic/ to git for team sharing/build-kb --fullUse Full Extraction (--full):
Use Incremental Update (default):
KB seems out of sync:
/build-kb --full # Force complete rebuild
Metadata corrupted:
rm .fellow-data/semantic/extraction_metadata.json
/build-kb # Will do full extraction
Incremental taking too long:
# If many files changed, consider full rebuild
/build-kb --full
.fellow-data/ (easy to gitignore or commit)