Help us improve
Share bugs, ideas, or general feedback.
From episteme
Software engineering knowledge graph — patterns, laws, refactorings, smells. Activates on any code quality concern, design decision, architecture review, or engineering question — even when the user describes problems informally. Uses Episteme HTTP API (resolved via `epis api env`) via curl.
npx claudepluginhub epicsagas/plugins --plugin epistemeHow this skill is triggered — by the user, by Claude, or both
Slash command
/episteme:epistemeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Hybrid search + graph traversal over a curated database of design patterns, engineering laws, code smells, and refactoring techniques. All queries use the Episteme HTTP API via curl.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
Hybrid search + graph traversal over a curated database of design patterns, engineering laws, code smells, and refactoring techniques. All queries use the Episteme HTTP API via curl.
Before any API call, resolve the URL and token once:
eval $(epis api env)
# Sets: EPISTEME_URL=http://127.0.0.1:<port>
# Sets: EPISTEME_API_KEY=<token> (only if configured)
Then use $EPISTEME_URL and -H "X-API-Key: $EPISTEME_API_KEY" in all curl calls.
curl -sf $EPISTEME_URL/health or start with epis api startX-API-Key: $EPISTEME_API_KEY| Arg | Action |
|---|---|
verify | Check server is running → eval $(epis api env) → curl $EPISTEME_URL/health → print status |
rag status | Same as verify |
Activate automatically when the user expresses any of the following, regardless of technical phrasing:
Code problems — translate complaint into a knowledge graph query:
| User says | API call (run via Bash) |
|---|---|
| "this class does too much" / file > 300 lines | curl -s '$EPISTEME_URL/search?q=god+class+large+class+single+responsibility&limit=5' |
| "this function is too long" | curl -s '$EPISTEME_URL/search?q=long+method+extract+method&limit=5' |
| "code is too complex" / hard to follow | curl -s '$EPISTEME_URL/search?q=complexity+smell+cognitive+overload&limit=5' |
| "calling DB directly in business logic" | curl -s '$EPISTEME_URL/search?q=coupling+persistence+repository+data+access+layer&limit=5' |
| "hard to test" / can't write unit tests | curl -s '$EPISTEME_URL/search?q=testability+dependency+injection+mockability&limit=5' |
| "copy-pasted this" / duplicated logic | curl -s '$EPISTEME_URL/search?q=duplicated+code+clone+smell&limit=5' |
| "changing X breaks Y" / change ripple | curl -s '$EPISTEME_URL/search?q=brittle+coupling+change+propagation+rigidity&limit=5' |
| "adding a new type means touching everywhere" / growing switch | curl -s '$EPISTEME_URL/search?q=open+closed+principle+strategy+polymorphism&limit=5' |
| "is this thread-safe?" / concurrency concerns | curl -s '$EPISTEME_URL/search?q=thread+safety+race+condition+shared+mutable+state&limit=5' |
| "API is slow" / performance issues | curl -s '$EPISTEME_URL/search?q=N%2B1+query+lazy+loading+caching+performance&limit=5' |
| User shares code for review | curl -s -X POST $EPISTEME_URL/analyze -H 'Content-Type: application/json' -d '{"code":"...","language":"python"}' then curl -s -X POST $EPISTEME_URL/refactor -H 'Content-Type: application/json' -d '{"code":"...","language":"python"}' |
| User wants to refactor or improve code | curl -s -X POST $EPISTEME_URL/refactor -H 'Content-Type: application/json' -d '{"code":"...","language":"python"}' |
Architecture discussions:
| User says | API call (run via Bash) |
|---|---|
| "microservices vs monolith" / how to split | curl -s '$EPISTEME_URL/search?q=monolith+microservice+decomposition+bounded+context&limit=5' |
| "is this architecture okay?" / architecture review | curl -s '$EPISTEME_URL/search?q=layered+architecture+coupling+cohesion+separation+concerns&limit=5' |
| "where should this go?" / code placement | curl -s '$EPISTEME_URL/search?q=responsibility+assignment+package+structure&limit=5' |
| Team/org structure affects code | curl -s '$EPISTEME_URL/search?q=Conway+law+organizational+structure+architecture&limit=5' |
Follow-up exploration:
| User says | API call (run via Bash) |
|---|---|
| Entity ID mentioned (DP-xxx, LAW-xxx, RF-xxx, SMELL-xxx) | curl -s '$EPISTEME_URL/graph/DP-005?detail=full' |
| "how does X relate to Y" | curl -s -X POST $EPISTEME_URL/graph/path -H 'Content-Type: application/json' -d '{"from_id":"DP-005","to_id":"SMELL-01","max_depth":5}' or curl -s '$EPISTEME_URL/graph/DP-005/neighbors' |
| "tell me more" about a result | curl -s '$EPISTEME_URL/graph/ID?detail=full' for full details, curl -s '$EPISTEME_URL/graph/ID/neighbors' for connections |
Always:
All commands use curl via the Bash tool. Add -H "X-API-Key: $EPISTEME_API_KEY" if auth is configured.
| Endpoint | Method | Purpose |
|---|---|---|
/search?q=QUERY&limit=N&type=TYPE | GET | Hybrid keyword + semantic search |
/search | POST | Search with JSON body: {"query":"...","limit":5,"entity_type":"pattern"} |
/graph/{ID}?detail=full | GET | Full details for a specific entity |
/graph/{ID}/neighbors?type=solves | GET | Explore related entities |
/graph/neighbors | POST | Neighbors with JSON body: {"entity_id":"DP-005","relation_type":"solves"} |
/graph/path | POST | Trace connection: {"from_id":"DP-005","to_id":"SMELL-01","max_depth":5} |
/analyze | POST | Detect code smells: {"code":"...","language":"python"} |
/refactor | POST | Ranked refactoring suggestions: {"code":"...","language":"python","top_k":3} |
/insights | POST | Add user insight: {"text":"...","tags":["t1"],"linked_entities":["DP-005"]} |
/graph/subgraph | POST | Extract subgraph around entity: {"entity_id":"DP-005","depth":2} |
/graph/contradictions | GET | List all conflicting entity pairs in the graph |
/graph/infer | GET | Infer transitive enforcement relationships |
/health | GET | Health check |
/stats | GET | Graph statistics |
# Search
curl -s '$EPISTEME_URL/search?q=dependency+injection&limit=5'
# POST search with entity type filter
curl -s -X POST $EPISTEME_URL/search \
-H 'Content-Type: application/json' \
-d '{"query":"dependency injection","limit":5,"entity_type":"pattern"}'
# Get entity details
curl -s '$EPISTEME_URL/graph/DP-005?detail=full'
# Get neighbors
curl -s '$EPISTEME_URL/graph/DP-005/neighbors?type=enforces'
# POST neighbors
curl -s -X POST $EPISTEME_URL/graph/neighbors \
-H 'Content-Type: application/json' \
-d '{"entity_id":"DP-005","relation_type":"enforces"}'
# Find path between entities
curl -s -X POST $EPISTEME_URL/graph/path \
-H 'Content-Type: application/json' \
-d '{"from_id":"DP-005","to_id":"SMELL-01","max_depth":5}'
# Analyze code
curl -s -X POST $EPISTEME_URL/analyze \
-H 'Content-Type: application/json' \
-d '{"code":"class GodClass { ... }","language":"python"}'
# Get refactoring suggestions
curl -s -X POST $EPISTEME_URL/refactor \
-H 'Content-Type: application/json' \
-d '{"code":"class GodClass { ... }","language":"python","top_k":3}'
# Add insight
curl -s -X POST $EPISTEME_URL/insights \
-H 'Content-Type: application/json' \
-d '{"text":"Team decided to use Repository pattern","tags":["decision"],"linked_entities":["DP-005"]}'
# Extract subgraph (depth=2 default)
curl -s -X POST $EPISTEME_URL/graph/subgraph \
-H 'Content-Type: application/json' \
-d '{"entity_id":"DP-005","depth":2}'
# List contradictions
curl -s '$EPISTEME_URL/graph/contradictions'
# Infer transitive enforcements
curl -s '$EPISTEME_URL/graph/infer'
For code analysis, pass the code string directly in the JSON body — no temp file needed:
# Analyze smells
curl -s -X POST $EPISTEME_URL/analyze \
-H 'Content-Type: application/json' \
-d '{"code":"class UserManager:\n def create(self): pass\n def delete(self): pass\n def email(self): pass","language":"python"}'
# Get ranked refactorings
curl -s -X POST $EPISTEME_URL/refactor \
-H 'Content-Type: application/json' \
-d '{"code":"class UserManager:\n def create(self): pass\n def delete(self): pass\n def email(self): pass","language":"python","top_k":3}'
Multi-step flows that chain API calls into end-to-end workflows. After each chain completes, present interactive follow-up options to the user.
curl -s -X POST $EPISTEME_URL/analyze -d '{"code":"...","language":"LANG"}'
-> curl -s -X POST $EPISTEME_URL/refactor -d '{"code":"...","language":"LANG"}'
-> curl -s '$EPISTEME_URL/graph/SMELL_ID/neighbors?type=solved_by'
-> curl -s -X POST $EPISTEME_URL/graph/path -d '{"from_id":"SMELL_A","to_id":"SMELL_B"}' [for each pair of detected smells]
-> Report with causation graph
-> Present options:
1. Apply refactoring [RF-xxx] -> spawn refactoring-expert agent
2. Deep dive into [SMELL-xxx] root cause -> spawn episteme-advisor agent
3. Architecture assessment -> spawn architecture-analyst agent
4. Explain [entity ID] in detail -> curl -s '$EPISTEME_URL/graph/ID?detail=full'
curl -s '$EPISTEME_URL/search?q=QUERY&limit=5'
-> curl -s '$EPISTEME_URL/graph/TOP_RESULT?detail=full'
-> curl -s '$EPISTEME_URL/graph/ENTITY/neighbors?type=enforces'
-> curl -s '$EPISTEME_URL/graph/ENTITY/neighbors?type=violates'
-> curl -s -X POST $EPISTEME_URL/graph/path -d '{"from_id":"ENTITY_A","to_id":"ENTITY_B"}'
-> Report with compliance scores and risk assessment
-> Present options:
1. Get refactoring plan for violations -> spawn code-reviewer agent
2. Advisory on resolving tensions -> spawn episteme-advisor agent
3. Research alternatives -> spawn episteme-researcher agent
4. Deep dive into specific law/pattern -> curl -s '$EPISTEME_URL/graph/ID?detail=full'
curl -s '$EPISTEME_URL/search?q=SYMPTOM_QUERY&limit=5'
-> curl -s '$EPISTEME_URL/graph/TOP_RESULT?detail=full'
-> curl -s '$EPISTEME_URL/graph/ENTITY/neighbors?type=solved_by'
-> curl -s '$EPISTEME_URL/graph/ENTITY/neighbors?type=violates'
-> Report: Root Cause -> Symptoms -> Fixes -> Trade-offs
-> Present options:
1. Apply recommended fix -> spawn refactoring-expert agent
2. Get advisory on approach -> spawn episteme-advisor agent
3. Verify fix works -> curl -s -X POST $EPISTEME_URL/refactor -d '{"code":"...","language":"python"}' on proposed solution
4. Explore related patterns -> curl -s '$EPISTEME_URL/graph/ID/neighbors?type=related_to'
curl -s '$EPISTEME_URL/search?q=TOPIC&limit=5'
-> curl -s '$EPISTEME_URL/graph/ID?detail=full' [for each result]
-> curl -s '$EPISTEME_URL/graph/ID/neighbors?type=related_to'
-> curl -s -X POST $EPISTEME_URL/graph/path -d '{"from_id":"ENTITY_A","to_id":"ENTITY_B"}' [for contrasting concepts]
-> Report: Core Concept -> Related -> Contrasting -> When to Use
-> Present options:
1. See practical code examples -> curl -s '$EPISTEME_URL/search?q=ENTITY+example&limit=5'
2. Apply this pattern to my code -> spawn code-reviewer agent
3. Compare alternatives -> spawn episteme-researcher agent
These rules ensure every API call leads naturally to the next:
| After running... | Always follow up with... |
|---|---|
POST /analyze | POST /refactor on the same code for ranked refactorings |
POST /refactor | GET /graph/{SMELL_ID}/neighbors?type=solved_by to check for alternative fixes |
GET /search | GET /graph/{ID}?detail=full on top 1-2 results for full context |
GET /graph/{ID}?detail=full (smell) | GET /graph/{ID}/neighbors?type=violates to find impacted principles |
GET /graph/{ID}?detail=full (pattern) | GET /graph/{ID}/neighbors?type=enforces to find enforced laws |
GET /graph/{ID}?detail=full (refactoring) | GET /graph/{ID}/neighbors?type=solved_by inverse to find what it solves |
| Multiple smells detected | POST /graph/path between smell pairs to map causation |
GET /graph/{ID}/neighbors returns >3 entities | Summarize and offer GET /graph/{ID}?detail=full on user's choice |
When presenting next-step options after any workflow chain, use this format:
## Next Steps
1. **[Action verb]** -- [Description] -> [agent name or API call]
2. **[Action verb]** -- [Description] -> [agent name or API call]
3. **[Action verb]** -- [Description] -> [agent name or API call]
Available agents for handoff:
episteme-advisor -- For trade-off analysis, decision guidance, and root-cause deep divesepisteme-researcher -- For broad research across entity types and finding alternativescode-reviewer -- For code smell detection, refactoring ranking, and causation analysisarchitecture-analyst -- For system-level evaluation against laws and structural risksrefactoring-expert (external) -- For implementing specific refactoring steps on codeHandoff rules:
curl -s -X POST $EPISTEME_URL/analyze -H 'Content-Type: application/json' -d '{"code":"...","language":"LANG"}' to detect smells.curl -s -X POST $EPISTEME_URL/refactor -H 'Content-Type: application/json' -d '{"code":"...","language":"LANG"}' for ranked fixes.curl -s '$EPISTEME_URL/graph/SMELL_ID?detail=full' to map it to principles and laws.curl -s -X POST $EPISTEME_URL/graph/path -H 'Content-Type: application/json' -d '{"from_id":"SMELL_A","to_id":"SMELL_B"}' to discover causation chains.curl -s '$EPISTEME_URL/search?q=QUERY&limit=5' with the core architectural question.curl -s '$EPISTEME_URL/graph/ID/neighbors' to find complementary and conflicting concepts.curl -s -X POST $EPISTEME_URL/graph/path -H 'Content-Type: application/json' -d '{"from_id":"ENTITY_A","to_id":"ENTITY_B"}' between opposing concepts to surface trade-off chains.curl -s '$EPISTEME_URL/search?q=QUERY&limit=5' with each, merge results by relevance score.curl -s '$EPISTEME_URL/graph/ID?detail=full'.curl -s '$EPISTEME_URL/graph/ID/neighbors' to find root causes.curl -s -X POST $EPISTEME_URL/graph/path -H 'Content-Type: application/json' -d '{"from_id":"SMELL_A","to_id":"SMELL_B"}' between related smells.DP-001 ... DP-NNNRF-001 ... RF-NNNLAW-001 ... LAW-NNNSMELL-001 ... SMELL-NNN