Analysis

docs/analysis/README.md

@@ -0,0 +1,31 @@
+# libspec — Analysis Artifacts
+
+This directory contains auto-generated architectural analysis of the **libspec** project (v10.3.2).
+
+## Contents
+
+| File                                                                  | Description |
+|-----------------------------------------------------------------------|-------------|
+| [overview.md](overview.md)                                            | Mid-to-high level description of how the application works |
+| [class_diagram_core.puml](class_diagram_core.svg)                     | Core `Spec` / `Ctx` class hierarchy |
+| [class_diagram_spec_types.puml](class_diagram_spec_types.svg)         | Built-in specification vocabulary types |
+| [class_diagram_infrastructure.puml](class_diagram_infrastructure.svg) | CLI, REPL, MCP server, AgentConfig, Watcher |
+| [class_diagram_data.puml](class_diagram_data.svg)                     | Data model classes (Component, Snapshot, Implemented) |
+| [activity_spec_compilation.puml](activity_spec_compilation.svg)       | How spec files are compiled into Components / XML |
+| [activity_diff_workflow.puml](activity_diff_workflow.svg)             | Spec diff swim-lane (user ↔ CLI ↔ Git ↔ engine) |
+| [activity_mcp_server.puml](activity_mcp_server.svg)                   | MCP server request-handling swim-lane |
+| [activity_agent_workflow.puml](activity_agent_workflow.svg)           | Full agent-driven developer workflow swim-lane |
+| [activity_agent_config.puml](activity_agent_config.svg)               | Agent-config installation swim-lane |
+
+## Rendering PlantUML
+
+```bash
+# Using the PlantUML JAR
+java -jar plantuml.jar docs/analysis/*.puml
+
+# Or, convert .puml to .svg using NPM's plantuml-cli
+$ npm i -g plantuml-cli
+$ plantuml-cli --svg docs/analysis/*.puml
+
+# Or with the VSCode PlantUML extension — open any .puml file and press Alt+D
+```

docs/analysis/activity_agent_config.puml

@@ -0,0 +1,83 @@
+@startuml activity_agent_config
+title libspec — Agent Configuration Installation Swim-lane\n(libspec agent-config <agent>)
+
+skinparam backgroundColor #FAFAFA
+skinparam activity {
+  BackgroundColor #F0FDF4
+  BorderColor #16A34A
+  ArrowColor #16A34A
+  FontName Helvetica
+  StartColor #16A34A
+  EndColor #16A34A
+}
+skinparam note {
+  BackgroundColor #FFFDE7
+  BorderColor #F59E0B
+}
+
+|#E8F5E9|Developer|
+start
+:Run **libspec agent-config <agent>**\n(or call MCP agent_config tool);
+
+|#EEF2FF|CLI / MCP (cli.py)|
+:get_agent_config(agent, project_root)\n→ lookup AgentConfig._registry[agent];
+
+|#F5F3FF|AgentConfig (agent_config.py)|
+:Instantiate concrete AgentConfig subclass\n(e.g. ClaudeConfig, GeminiConfig, …);
+:Resolve uv path (local or PATH);
+
+' ── Write MCP server config ──
+:_backup_if_exists(config_path);
+:_load_json/toml_config(config_path);
+:Inject mcpServers.libspec entry\n→ {command: uv, args: [run libspec mcp], cwd};
+:_save_json/toml_config(config_path);
+
+note right
+  Config locations per agent:
+  claude    → .claude/settings.json
+  gemini    → .gemini/settings.json
+  antigravity → .gemini/antigravity/mcp_config.json
+  copilot   → .github/mcp.json
+  codex     → .codex/config.toml
+  opencode  → .opencode/opencode.json
+end note
+
+' ── Optional: run agent CLI ──
+if (Agent has native CLI?) then (yes)
+  :Run: antigravity --add-mcp …\nor: gemini mcp add …\netc.;
+  if (CLI succeeded?) then (yes)
+    :Mark as configured_via_cli;
+  else (no / not found)
+    :Fall back to file-only config;
+  endif
+endif
+
+' ── Render & install skill ──
+:_render_skill()\n→ Jinja2 render of skill.md.j2\nwith agent_id, workflow text;
+
+|#FFF3E0|skillkit|
+:SkillParser().parse_skill_file(temp_path)\n(validate YAML frontmatter);
+
+|#FFF3E0|skillkit|
+if (Validation OK?) then (yes)
+  |#F3E5F5|Filesystem|
+  :Rename TEMP_SKILL.md → SKILL.md\nin agent skill dir;
+else (no)
+  |#F5F3FF|AgentConfig (agent_config.py)|
+  :Raise ValueError\n"Skill Integrity Failure";
+  |#E8F5E9|Developer|
+  :Error shown;
+  stop
+endif
+
+|#F5F3FF|AgentConfig (agent_config.py)|
+:Return success message;
+
+|#EEF2FF|CLI / MCP (cli.py)|
+:Print / return result;
+
+|#E8F5E9|Developer|
+:Agent can now invoke libspec\ntools and follow SKILL.md workflow;
+stop
+
+@enduml

docs/analysis/activity_agent_workflow.puml

@@ -0,0 +1,127 @@
+@startuml activity_agent_workflow
+title libspec — Full Agent-Driven Developer Workflow Swim-lane\n(8-step spec-driven development cycle)
+
+skinparam backgroundColor #FAFAFA
+skinparam activity {
+  BackgroundColor #FFF7ED
+  BorderColor #EA580C
+  ArrowColor #EA580C
+  FontName Helvetica
+  StartColor #EA580C
+  EndColor #EA580C
+}
+skinparam note {
+  BackgroundColor #FFFDE7
+  BorderColor #F59E0B
+}
+
+|#FEF9C3|Developer (Human)|
+start
+:Decide on a feature\nor bug-fix goal;
+:Tell AI agent the task;
+
+|#FFF7ED|AI Coding Agent|
+note right
+  Agent has read SKILL.md
+  which contains the 8-step workflow.
+end note
+
+' ──────── STEP 1 ────────
+:STEP 1 — **Edit Spec**\nDecompose broad requirement into\ngranular single-responsibility\nCtx subclasses in spec/*.py;
+
+|#F0FDF4|Source Code / Tests|
+:Write / update spec/*.py\nwith new Requirement / Feature classes;
+
+' ──────── STEP 2 ────────
+|#FFF7ED|AI Coding Agent|
+:STEP 2 — **Diff Spec** (MANDATORY);
+
+|#EEF2FF|libspec MCP Tools|
+:Call **diff** tool\n(or: uv run libspec diff);
+
+|#F3E5F5|Git|
+:compile_live_spec() vs HEAD\ngenerate_native_patch();
+
+|#EEF2FF|libspec MCP Tools|
+:Return [NEW] / [CHANGED] / [REMOVED]\nrequirement-level patch;
+
+|#FFF7ED|AI Coding Agent|
+if (Any spec changes?) then (yes)
+  :Review mutations and\nnew requirements;
+else (no)
+  :Specs unchanged;\nNo implementation work needed;
+  stop
+endif
+
+' ──────── STEP 3 ────────
+:STEP 3 — **Sort Implementation Order**;
+
+|#EEF2FF|libspec MCP Tools|
+:Call **list_dependencies** tool\n(or: uv run libspec dependencies);
+:Return component inheritance graph;
+
+|#FFF7ED|AI Coding Agent|
+:Topologically sort components;\nIdentify foundational requirements\nto implement first;
+
+' ──────── STEP 4 ────────
+:STEP 4 — **Test Driven Development**;
+
+|#F0FDF4|Source Code / Tests|
+:Write failing tests for each\ncomponent in topological order;\nRun test suite → RED;
+
+' ──────── STEP 5 ────────
+|#FFF7ED|AI Coding Agent|
+:STEP 5 — **Implement**;
+
+|#F0FDF4|Source Code / Tests|
+:Implement components to pass tests;\nAdd REQUIREMENT-ID comments\nin source for cross-reference;
+:Run test suite → GREEN;
+
+' ──────── STEP 6 ────────
+|#FFF7ED|AI Coding Agent|
+:STEP 6 — **Code Quality**;
+
+|#F0FDF4|Source Code / Tests|
+:Run linter (ruff), formatter,\nstatic analysis (mypy),\ndead-code checks;
+
+' ──────── STEP 7 ────────
+|#FFF7ED|AI Coding Agent|
+:STEP 7 — **Verify Spec Sync**;
+
+|#EEF2FF|libspec MCP Tools|
+:Call **diff** tool again;
+
+|#F3E5F5|Git|
+:Recompile live spec\nvs HEAD;
+
+|#FFF7ED|AI Coding Agent|
+if (All changes\naccounted for?) then (yes)
+  :Specs and implementation\nare in sync ✓;
+else (no)
+  :Return to STEP 5\n(implement missing items);
+  note right
+    Loop until diff shows
+    no unimplemented changes.
+  end note
+  :STEP 5 — Implement;
+  |#F0FDF4|Source Code / Tests|
+  :Fill remaining implementation gaps;
+  |#FFF7ED|AI Coding Agent|
+  :STEP 7 — Verify Spec Sync (again);
+endif
+
+' ──────── STEP 8 ────────
+:STEP 8 — **Author Git Commit Message**;
+
+|#FEF9C3|Developer (Human)|
+:Review commit message\nand approve;
+
+|#F3E5F5|Git|
+:git commit -m "…";
+:git push;
+
+|#FEF9C3|Developer (Human)|
+:Feature complete ✓;
+stop
+
+@enduml

docs/analysis/activity_diff_workflow.puml

@@ -0,0 +1,90 @@
+@startuml activity_diff_workflow
+title libspec — Spec Diff Swim-lane\n(libspec diff / spec_diff.generate_native_patch)
+
+skinparam backgroundColor #FAFAFA
+skinparam activity {
+  BackgroundColor #F0FDF4
+  BorderColor #16A34A
+  ArrowColor #16A34A
+  FontName Helvetica
+  StartColor #16A34A
+  EndColor #16A34A
+}
+skinparam note {
+  BackgroundColor #FFFDE7
+  BorderColor #F59E0B
+}
+
+|#E8F5E9|User / Agent|
+start
+:Run **libspec diff [A] [B]**\nor call MCP **diff** tool;
+
+|#EEF2FF|CLI / MCP (cli.py / mcp_server.py)|
+:Validate .libspec/ project marker;
+:Call **generate_native_patch**(old, new);
+
+|#F0FDF4|spec_diff.py|
+:Resolve diff targets\n(_resolve_diff_targets);
+
+if (No args?) then (yes)
+  :old_commit = "HEAD"\nis_new_pending = True;
+else if (One arg?) then (yes)
+  :new_commit = "HEAD";
+endif
+
+|#FFF3E0|util.py|
+if (new is live?) then (yes)
+  :compile_live_spec()\n→ new_components;
+else (no)
+  |Git|
+  :git archive --format=tar {ref} spec\n| tar -xC /tmp/…;
+  |util.py|
+  :compile_live_spec(tmpdir)\n→ new_components;
+endif
+
+|#F3E5F5|Git|
+:git diff --quiet HEAD -- spec\n(check if live == HEAD);
+
+|#FFF3E0|util.py|
+:compile_git_spec(old_commit)\n→ old_components;
+
+note right
+  Git archive extracts spec/
+  into a temp dir; compiler
+  runs there then cleans up.
+end note
+
+|#F0FDF4|spec_diff.py|
+:Build old_map & new_map\n{ref → Component};
+:Compute all_refs = union of keys;
+
+repeat
+  :Take next ref;
+  if (only in new?) then (yes)
+    :Record **[NEW]** entry;
+  else if (only in old?) then (yes)
+    :Record **[REMOVED]** entry;
+  else (changed?)
+    :_compare_components_natively\n(old, new, maps, cache);
+    note right
+      Compares:
+      1. docstring (unified diff)
+      2. inherits list
+      3. recursive parent diffs
+    end note
+    if (hash differs?) then (yes)
+      :Record **[CHANGED]** entry\nwith change detail list;
+    endif
+  endif
+repeat while (more refs?) is (yes)
+
+:Collect unresolved_inherited_refs\n(refs in inherits not in new_map);
+
+|#EEF2FF|CLI / MCP (cli.py / mcp_server.py)|
+:Print / return patch output\n([NEW], [REMOVED], [CHANGED],\n[WARNING] unresolved refs);
+
+|#E8F5E9|User / Agent|
+:Review spec drift;\nProceed with implementation;
+stop
+
+@enduml