Imported from thatsme/giulia (SKILL.md). Install upstream with npx skills add thatsme/giulia. Copyright stays with the author.

SKILL.md — Giulia Code Intelligence

What is Giulia?

Giulia is a REST API daemon (port 4000) that provides AST-level code intelligence for Elixir projects. It maintains a persistent Property Graph, ETS-backed module/function index, and Sourceror-parsed AST cache across sessions. Prefer Giulia's API over shell tools (grep, find, cat) when the daemon is available — it returns structured, pre-indexed data instantly.

Detection

Before using any Giulia endpoint, verify the daemon is running:

curl -s http://localhost:4000/health

Expected: {"status":"ok","node":"...","version":"..."}. If this fails, fall back to standard file tools. Do not retry.

Access Methods

Giulia supports two access methods:

MCP setup: Place a .mcp.json in your project root pointing to http://localhost:4000/mcp with the Bearer token. In Claude Code, run /mcp to connect. All 74 skill endpoints become available as native tool calls (e.g., knowledge_stats, index_modules, brief_architect).

MCP tool naming: GET /api/knowledge/stats → tool name knowledge_stats. Strip method, strip /api/, replace / with _.

When MCP is connected, prefer MCP tool calls over curl — they return structured JSON directly without HTTP boilerplate.

Discovery (Build 98)

Every endpoint carries a @skill annotation. Instead of memorizing routes, discover them at runtime:

Each skill returns: intent, endpoint, params, returns, category.

Session Start (MANDATORY)

Before any work, always call the Architect Brief to get full project situational awareness:

This single call returns everything needed to understand a project's current state. Zero manual prompting — start every session with this.

Tool Categories

0. Daemon Operations

Lifecycle, status, and project management endpoints. These are core daemon routes (not @skill-annotated, so they don't appear in discovery).

1. Understanding Code

Use these to inspect modules, functions, types, and dependencies before making changes.

2. Analyzing Impact

Use these BEFORE modifying any shared module. They reveal the blast radius.

3. Intelligence (Pre-Processing Layers)

Giulia's intelligence layer runs before the LLM. It combines semantic search (Bumblebee embeddings) with Property Graph enrichment to produce structured context automatically.

Preflight Contract Checklist (POST /api/briefing/preflight) is the primary planning endpoint. Body:

{"prompt": "Refactor the approval flow", "path": "C:/Development/GitHub/Giulia", "top_k": 5, "depth": 2}

Given a natural language prompt, it:

1. Discovers relevant modules via semantic search (Bumblebee embeddings)
2. Pre-computes change risk scores (called once, cached in pipeline)
3. Builds 6 contract sections per module:
   • Behaviour Contract — callbacks defined/implemented, optional callbacks, integrity status (4-level: consistent, consistent_with_optionals, heuristic_match, fractured), missing callbacks, optional omitted, heuristic injected
   • Type Contract — specs with full signatures, types, spec coverage ratio
   • Data Contract — struct fields, dependents count
   • Macro Contract — use directives, known implications (GenServer requires init/1, etc.)
   • Topology — centrality, dependents list, change risk score/rank, full impact map
   • Semantic Integrity — cosine similarity to prompt, drift flag if module doesn't match intent
4. Summarizes aggregate counts: hubs, high-risk modules, fractured behaviours, semantic drift
5. Returns suggested_tools — top 5 API skills ranked by cosine similarity to the prompt (Build 100)

One call replaces the 4 separate queries previously required for planning mode.

Surgical Briefing (GET /api/intelligence/briefing) is the lighter alternative, used automatically during inference:

1. Layer 1 (Bumblebee): Finds the top 3 most relevant modules and top 5 functions via cosine similarity
2. Layer 2 (Property Graph): Enriches each module with centrality (hub score), dependents count, and file path
3. Returns a formatted briefing with hub warnings for high-centrality modules (in_degree >= 3)

4. Runtime Introspection (Build 92)

Live BEAM runtime awareness — what your code is doing right now, not just what it is.

All runtime endpoints accept an optional ?node=N parameter (default: local Giulia node). The ?path=P parameter on hot_spots enables Property Graph fusion.

5. Performance Profiling (Build 131+)

Burst analysis captures performance profiles during load spikes. Profiles persist across restarts.

When to use: After a performance incident or when investigating slowness. profile/latest gives you the most recent burst analysis with hot modules already identified. Cross-reference with hot_spots (Section 4) for Property Graph fusion — profiles show WHAT was hot, hot_spots shows WHY (complexity, centrality).

6. Fused Observations (Build 131+)

Observations combine Monitor-pushed runtime snapshots with Worker static analysis for the highest-fidelity view.

When to use: When you need to understand not just which processes are busy, but which modules are hot and what their graph properties are. A fused observation maps PID -> Module -> Property Graph vertex — runtime meets static analysis.

7. Monitor (Build 95)

Real-time telemetry dashboard and event stream for OODA pipeline, LLM calls, tool executions, and API requests.

When to use: The SSE stream is useful during inference to watch OODA steps in real time. The observation endpoints are used by the Monitor container to coordinate with the Worker for fused profiling (Sections 5-6).

8. Plan Validation Gate (Build 93)

After planning, before writing code: validate your plan against the Property Graph.

Request format:

{
  "path": "C:/Development/GitHub/Giulia",
  "plan": {
    "modules_touched": ["Giulia.Context.Store", "Giulia.Knowledge.Store"],
    "actions": [
      {"type": "modify", "module": "Giulia.Context.Store"},
      {"type": "create", "module": "Giulia.Runtime.Inspector", "depends_on": ["Giulia.Knowledge.Store"]}
    ]
  }
}

Five validation checks:

1. Cycle detection — clones graph, adds proposed edges, detects new circular dependencies -> rejected if new cycles
2. Red zone collision — counts red-zone modules (heatmap score >=60) in plan -> warning if >=2 red zones touched
3. Hub risk aggregation — sums centrality degrees across touched modules -> warning if total > 40
4. Blast radius preview — union of all downstream dependents -> info with count
5. Unprotected hub write — checks if plan modifies hub modules with low spec coverage -> warning with coverage data

Verdicts:

• approved — all checks pass, proceed without justification
• warning — acknowledge each warning and explain why you're proceeding
• rejected — do not write code, revise the plan first

9. Modifying Code

Send natural language commands through Giulia's OODA orchestrator. Two endpoints available (not @skill-annotated — daemon core routes):

Request format:

{"message": "your instruction here", "path": "C:/Development/GitHub/ProjectName"}

Good commands (specific, actionable, name the tool when possible):

"In Giulia.Tools.Registry, rename the function 'execute' to 'dispatch'. Use rename_mfa."
"Add a @spec to all public functions in Giulia.Context.Store."
"Extract the private helpers parse_args/1 and validate_opts/1 from Giulia.Inference.Orchestrator into a new module Giulia.Inference.Utils."
"In Giulia.Tools.ReadFile, add a max_lines parameter with default 1000. Update the execute/2 function to respect it."
"Replace all occurrences of 'alias Giulia.Old.Module' with 'alias Giulia.New.Module' across the codebase."

Poor commands (vague, the orchestrator will loop):

"Make the code better."
"Fix all the bugs."
"Refactor everything."

Boundaries: The orchestrator works best with single, concrete tasks. It can handle multi-file changes atomically but struggles with open-ended exploration. For tasks like "understand this codebase" or "find all performance bottlenecks," use the read-only endpoints directly.

SSE event types returned by the stream:

• model_detected — which LLM model is handling the request
• tool_call / tool_result — tool invoked and its outcome
• transaction_auto_enabled — staging mode activated (hub module detected)
• commit_started / commit_compiling / commit_compile_passed / commit_integrity_passed / commit_success — transactional commit lifecycle
• tool_requires_approval — dangerous operation needs approval (see Approval Flow below)
• complete — final response with result

10. Approval Flow

When the orchestrator encounters a high-risk operation (writing to a hub module with centrality > 3), it emits tool_requires_approval with an approval_id. To proceed:

1. Present the operation details to the user (tool name, parameters, preview diff)
2. If the user approves: POST /api/approval/:approval_id with {"approved": true}
3. If the user rejects: POST /api/approval/:approval_id with {"approved": false}
4. Do NOT auto-approve — the approval gate exists to catch destructive changes to critical modules

11. Transaction Mode

Staging buffer for atomic multi-file changes with compile-check gates.

12. Verifying Changes

Workflow Guidance

Planning Mode (MANDATORY)

When entering plan mode for any Elixir code modification, you MUST query Giulia's analysis endpoints BEFORE writing the plan. Do NOT use grep, awk, sed, or find to discover module dependencies — Giulia's Property Graph has this data pre-indexed from AST analysis.

First call MUST be Preflight:

curl -X POST http://localhost:4000/api/briefing/preflight \
  -H "Content-Type: application/json" \
  -d '{"prompt":"your task description","path":"C:/Development/GitHub/ProjectName"}'

This single call returns all 6 contract sections per relevant module — behaviour obligations, type contracts, struct dependencies, macro implications, topology (centrality + impact + change risk), and semantic integrity. One call replaces four.

For modules NOT in the preflight result (or for deeper investigation), use individual queries:

1. GET /api/knowledge/change_risk?path=P — identify which modules are dangerous to touch
2. GET /api/knowledge/impact?path=P&module=X&depth=2 — blast radius for every module you plan to modify
3. GET /api/knowledge/centrality?path=P&module=X — hub score (degree > 3 = high-risk)
4. GET /api/index/module_details?path=P&module=X — full API surface of target modules
5. POST /api/knowledge/pre_impact_check — before renaming/removing a function or module, get affected callers, risk score, and phased migration plan
6. GET /api/knowledge/heatmap?path=P — module health overview: red/yellow/green zones by composite score
7. GET /api/knowledge/logic_flow?path=P&from=MFA&to=MFA — trace function-call path between two MFA vertices
8. GET /api/knowledge/audit?path=P — unified audit combining unprotected hubs, struct lifecycle, semantic duplicates, and behaviour integrity in one call
9. GET /api/knowledge/unprotected_hubs?path=P — find hub modules with insufficient spec/doc coverage (dangerous gaps)
10. GET /api/knowledge/struct_lifecycle?path=P — trace struct data flow across modules (creators, consumers, logic leaks)
11. GET /api/knowledge/duplicates?path=P — find semantically similar functions via embedding cosine similarity
12. GET /api/index/complexity?path=P&module=X — rank functions by cognitive complexity within a module (pinpoint WHERE complexity concentrates)
13. GET /api/knowledge/style_oracle?path=P&q=Q — find exemplar functions by concept for consistent style

No plan is valid without blast radius data. If you skip preflight AND these queries, the plan is incomplete.

Planning Protocol (NON-NEGOTIABLE)

When formulating a multi-file refactor or any modification touching 2+ modules:

1. You MUST format your plan as a JSON object matching the /api/plan/validate schema
2. You MUST call POST /api/plan/validate with that plan
3. If the verdict is REJECTED, you are FORBIDDEN from writing code. Revise the plan.
4. If the verdict is WARNING, you must acknowledge each warning and explain why you're proceeding
5. Only APPROVED plans may be executed without justification

Before Modifying Any Elixir Module

1. Understand — GET /api/index/module_details?path=P&module=X to get the full picture (functions, types, specs, callbacks)
2. Assess impact — GET /api/knowledge/impact?path=P&module=X&depth=2 to see who depends on it and what it depends on
3. Check hub score — GET /api/knowledge/centrality?path=P&module=X — if degree > 3, changes are high-risk
4. Check complexity — GET /api/index/complexity?path=P&module=X — identify the most complex functions before modifying
5. Make changes — edit files directly or use POST /api/command/stream for complex refactoring
6. Re-index — POST /api/index/scan so the index reflects your changes
7. Verify integrity — GET /api/knowledge/integrity?path=P to catch behaviour-implementer fractures early

AST Cache + Warm Starts (Build 102-104)

Giulia persists all AST data, the Property Graph, metric caches, and embeddings to disk via CubDB at {project}/.giulia/cache/cubdb/. On restart, the daemon restores from cache instead of re-scanning — zero cold starts for unchanged files. The cache lives on the bind-mounted volume, so it survives Docker image rebuilds.

Check cache status before triggering a scan:

curl -s "http://localhost:4000/api/index/status"

Response includes cache_status ("warm", "cold", or "no_project") and merkle_root (truncated SHA-256). If cache_status is "warm", a scan will only re-index files that changed on disk.

Invalidation rules:

• File content changed on disk -> only that file is re-scanned (incremental, via SHA-256 content hash)
• File deleted -> removed from cache automatically
• Build number mismatch (daemon upgraded) -> full cold start (AST data shape may have changed)
• Cache absent or corrupted -> full cold start

Key point: You do NOT need to avoid POST /api/index/scan for performance. The Loader detects stale files via SHA-256 content hashes and only re-indexes what changed. A warm scan of an unchanged project completes in milliseconds.

Critical Rule: Re-index After Direct Edits

If you edit Elixir files directly (using file write/edit tools instead of Giulia's command/stream), the ETS index and Property Graph become stale. Always call POST /api/index/scan after direct file modifications. Without this, subsequent calls to /api/index/* and /api/knowledge/* will return outdated information. The cache layer ensures only modified files are actually re-scanned.

Choosing Giulia vs Shell Tools

Report Output Convention (MANDATORY)

When a report or assessment is requested (project audit, health check, analysis, code review, etc.), you MUST produce a comprehensive Markdown report file with this naming convention:

<projectfolder>_REPORT_<AAAAMMHH>.md

• <projectfolder> — the project directory name (e.g., Giulia, MyApp)
• <AAAAMMHH> — timestamp: year (4 digits) + month (2 digits) + hour (2 digits)

Example: Giulia_REPORT_20260211.md

The report must be saved in the project root. Do not skip file creation — a verbal summary alone is insufficient when a report or assessment is requested. Follow GET /api/intelligence/report_rules for the canonical report structure.

Path Convention

All index and knowledge endpoints require a ?path=P query parameter identifying which project to query. This is because Giulia supports multi-project isolation — each scanned project has its own ETS namespace and Property Graph. Without ?path=, these endpoints return a 400 error.

Use the host path (e.g., path=C:/Development/GitHub/Giulia). The daemon translates to container paths automatically via PathMapper.

Example: GET /api/knowledge/stats?path=C:/Development/GitHub/Giulia

The POST /api/index/scan and POST /api/command/stream endpoints take path in the JSON body instead (unchanged).