Add Ontoly software graph analysis skill

README.md

@@ -2,11 +2,11 @@
 
 Open-source operating kit for people using OpenAI Codex and ChatGPT to think, write, analyze, decide, automate routine work, and ship better output with more consistency.
 
-CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 90 skills across 15 work domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, sales, IT & admin, training & development, founder workflows, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths.
+CodexKit is a fresh project rebuilt around the surfaces that matter in Codex today: local Skills, high-signal playbooks, automation recipes, operational templates, department starter workspaces, repo guardrails, and MCP onboarding guidance. The pack covers 91 skills across 15 work domains: engineering workflows, high-reasoning work, and low-reasoning office automation across project management, finance, legal, HR, operations, supply chain, strategy, analytics, marketing, data, customer success, sales, IT & admin, training & development, founder workflows, and cross-functional work. It follows the official Codex Skills layout with `SKILL.md`, optional `agents/openai.yaml`, and standard `.agents/skills` discovery paths.
 
 ## What is included
 
-- `skills/`: 90 installable Codex Skills across 15 work domains — engineering, high-reasoning business work, and low-reasoning office automation.
+- `skills/`: 91 installable Codex Skills across 15 work domains — engineering, high-reasoning business work, and low-reasoning office automation.
 - `playbooks/`: copy-ready prompts for clarify, execute, review, decision, delegation, and release work.
 - `automations/`: 14 recurring task recipes for engineering plus weekly business, close, hiring, legal intake, operations, marketing, standups, meeting follow-ups, and OKR routines.
 - `mcp/`: practical guidance for choosing and rolling out MCP servers without overloading the team.
@@ -36,7 +36,7 @@ If you do not want to use Git commands or remember terminal steps, use the GitHu
 4. On Windows, double-click `START-HERE-WINDOWS.cmd`.
    - If Codex is not installed, the script will show installation instructions.
 5. Restart Codex.
-6. In Codex, type `/skills` to confirm all 90 skills appear.
+6. In Codex, type `/skills` to confirm all 91 skills appear.
 7. Open `skill-finder.md` to browse skills by situation.
 7. Optional: double-click `CREATE-WORKSPACE-WINDOWS.cmd` to create a starter workspace.
 
@@ -209,7 +209,7 @@ Every skill addresses five concerns: **Intent** (clear purpose), **Knowledge** (
 
 | Tier | Structure | Current coverage |
 |------|-----------|------------------|
-| **1** | `SKILL.md` + `agents/openai.yaml` | All 90 skills |
+| **1** | `SKILL.md` + `agents/openai.yaml` | All 91 skills |
 | **2** | + `verification/` + `examples/` | 26 high-value skills |
 | **3** | + `templates/` + `scripts/` | 5 technical skills |
 
@@ -220,7 +220,7 @@ Every skill addresses five concerns: **Intent** (clear purpose), **Knowledge** (
 | `knowledge` | 17 |
 | `data` | 16 |
 | `scaffolding` | 16 |
-| `runbook` | 10 |
+| `runbook` | 11 |
 | `verification` | 9 |
 | `automation` | 9 |
 | `review` | 9 |

skill-finder.md

@@ -1,6 +1,6 @@
 # Skill Finder — "I need to… → Use this skill"
 
-> Quick reference for all 90 CodexKit skills grouped by what you're trying to accomplish.
+> Quick reference for all 91 CodexKit skills grouped by what you're trying to accomplish.
 
 ---
 
@@ -14,7 +14,7 @@
 | `data` | Read, process, analyze, or visualize data | 16 |
 | `automation` | Chain repeatable steps into workflows | 9 |
 | `verification` | Validate, audit, or test outputs against standards | 9 |
-| `runbook` | Step-by-step procedures for recurring operational situations | 10 |
+| `runbook` | Step-by-step procedures for recurring operational situations | 11 |
 | `infra` | Technical delivery, CI/CD, system checks, governance | 4 |
 
 > Each skill's `SKILL.md` frontmatter includes a `category` field. See `templates/SKILL-TEMPLATE.md` for authoring guidelines.
@@ -161,6 +161,7 @@
 | I need to… | Skill | What it does |
 |---|---|---|
 | Onboard to a new codebase | `codexkit-repo-onboarding` | Map runtime model, risk zones, first next steps |
+| Answer codebase questions from a Software Graph | `codexkit-software-graph-analysis` | Uses Ontoly graph evidence for architecture, impact, routes, services, and dependencies |
 | Get started with MCP | `codexkit-mcp-onboarding` | Evaluate and phase MCP adoption |
 | Do a risk‑first code review | `codexkit-high-signal-review` | Bugs, regressions, missing tests, operational gaps |
 | Harden test coverage | `codexkit-test-hardening` | Edge cases and regressions without noisy tests |

skills/codexkit-software-graph-analysis/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: codexkit-software-graph-analysis
+description: Use Ontoly to answer codebase architecture, dependency, route, service, and impact questions from a deterministic Software Graph.
+version: 1.0.0
+category: runbook
+---
+
+# Software Graph Analysis
+
+Use this skill when a software question should be answered from repository structure, symbol relationships, framework concepts, dependency edges, or request-flow evidence instead of repeated file search.
+
+## Objectives
+
+- verify whether an Ontoly Software Graph already exists
+- build or refresh the graph when it is missing or stale
+- query Ontoly before opening source files
+- cite graph evidence, node IDs, relationships, diagnostics, and confidence
+- fall back to source inspection only when the graph cannot answer
+
+## Workflow
+
+1. Locate the repository root and check for `.ontoly/SoftwareGraph.json` or an explicitly supplied graph path.
+2. If no graph exists, run `ontoly build .` from the repository root and capture diagnostics.
+3. Check graph metadata, diagnostics, trust, coverage, and graph hash before relying on answers.
+4. Use Ontoly CLI or MCP capabilities for the question:
+   - architecture or onboarding: architecture summary, packages, modules, services
+   - impact questions: impact analysis and dependency traversal
+   - request flow: route trace or execution trace
+   - configuration: configuration and environment-variable usage
+   - dead code: graph diagnostics and unreachable nodes
+5. Produce the answer with evidence: relevant nodes, edges, source locations, diagnostics, and confidence.
+6. Inspect source files only for missing graph coverage, ambiguous results, or verification of a suspected graph gap.
+7. If Ontoly cannot answer, say exactly which graph evidence is missing and recommend a specific analyzer or graph-quality improvement.
+
+## Inputs
+
+| Input | Required | Format |
+|-------|----------|--------|
+| Repository path | Yes | Local path or current workspace |
+| User question | Yes | Architecture, impact, route, dependency, or configuration question |
+| Ontoly graph | Recommended | `.ontoly/SoftwareGraph.json` or generated by `ontoly build .` |
+| Constraint | Optional | Package, framework, node name, route, or file path to focus on |
+
+## Output
+
+Produce a compact evidence-backed analysis:
+
+```markdown
+## Software Graph Answer
+
+### Answer
+{Direct answer in 1-3 paragraphs.}
+
+### Evidence
+| Evidence | Source |
+|----------|--------|
+| Node | `{node id}` |
+| Edge | `{source} --RELATIONSHIP--> {target}` |
+| Location | `{file}:{line}` |
+
+### Confidence
+{High, Medium, or Low} because {graph evidence and diagnostics}.
+
+### Gaps
+{Missing coverage, ambiguous nodes, or source fallback used.}
+```
+
+## Quality Criteria
+
+- [ ] The answer starts from Ontoly graph evidence, not file search.
+- [ ] Every major claim cites at least one node, edge, diagnostic, graph statistic, or source location.
+- [ ] Confidence is derived from graph evidence and diagnostics, not guessed.
+- [ ] Source inspection is explicitly labeled as fallback evidence when used.
+
+## Verification (4C)
+
+| Check | Question |
+|-------|----------|
+| **Correctness** | Does the answer match the graph nodes, relationships, source locations, and diagnostics? |
+| **Completeness** | Are relevant callers, callees, dependencies, routes, modules, configuration, or services included for the question? |
+| **Context-fit** | Does the explanation match the user's requested scope instead of dumping the full graph? |
+| **Consequence** | If a developer acted on this answer, what could break if an edge or node was missing? |
+
+## Edge Cases
+
+- **Ontoly is not installed** — Ask to install it or use `npx ontoly build .` if the package is publicly available in the environment.
+- **Graph build fails** — Report the command, exit code, diagnostics, and the smallest reproducible blocker.
+- **Ambiguous node name** — List candidates with node IDs, kinds, and source locations before answering.
+- **Low graph trust or coverage** — Answer only the evidenced part and recommend targeted graph validation before using the result for a change plan.
+- **Repository is huge** — Start with architecture, package, module, and service summaries before expanding to functions.
+
+## Examples
+
+> **Good:** "AuthService depends on UserRepository through an INJECTS edge and is called by AuthController for POST /login. Confidence is High because the route, controller, service, and dependency edges all exist in the graph."
+
+> **Bad:** "I searched the repo and it looks like auth is probably in `src/auth`." This bypasses the Software Graph and gives no deterministic evidence.
+
+## Definition of Done
+
+- [ ] Ontoly graph existence and freshness checked.
+- [ ] Relevant Ontoly query or MCP capability used.
+- [ ] Answer includes graph evidence and confidence.
+- [ ] Missing graph coverage is called out as a gap, not hidden by source search.
+
+## Changelog
+
+- v1.0.0 — Initial release

skills/codexkit-software-graph-analysis/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Software Graph Analysis"
+  short_description: "Answer codebase questions with Ontoly graph evidence."
+  default_prompt: "Use $codexkit-software-graph-analysis to answer this repository question from Ontoly Software Graph evidence."
+  brand_color: "#2563EB"