twining-map

Twining Map — Knowledge Graph Building (Optional)

This is an advanced, opt-in workflow. Benchmark data shows graph building has no measurable correlation with coordination quality (r=-0.01). Use only when you specifically need structural analysis. Requires graph.auto_populate: true in config for auto-population, or manual entity/relation creation.

Tool availability. The graph tools below (twining_add_entity, twining_add_relation, twining_neighbors, twining_graph_query, twining_prune_graph) are on the default surface. twining_decide and twining_verify, referenced below, require tools.full_surface: true — on a default install use twining_record's decisions array instead, which populates the same affected_files / affected_symbols entities.

Build the knowledge graph to capture architectural relationships when you need to reason about code structure across multiple modules.

When to Invoke

• When you need to understand cross-module dependencies for impact analysis
• When onboarding to a complex area where structural relationships aren't obvious from code alone
• When explicitly asked to map code structure

When NOT to Invoke

• For most day-to-day coordination work (use decisions and blackboard instead)
• Trivial decisions (naming, formatting, config values)
• Changes that don't alter code structure
• When the graph already has the information (check first with twining_neighbors)

Workflow

1. Add Entities

Call twining_add_entity for each significant code component:

• name: Unique identifier (e.g., "AuthMiddleware", "src/auth/middleware.ts")
• type: One of module, function, class, file, concept, pattern, dependency, api_endpoint
• properties: Key-value metadata (e.g., { file: "src/auth/middleware.ts", layer: "engine" })

Note: twining_decide auto-creates file and function entities for affected_files and affected_symbols. You only need to manually add entities for richer structural information.