engineering-intelligence 0.2.0

package/templates/canonical/rules/engineering-intelligence.md

@@ -0,0 +1,22 @@
+# Engineering Intelligence Rules
+
+When `knowledge-base/` exists, consult its relevant documents, `.engineering-intelligence/context/`, and `.engineering-intelligence/graph/` before non-trivial project edits.
+
+For engineering changes:
+
+1. Write an impact report before editing.
+2. Modify code and tests appropriate to the request.
+3. Validate honestly and report unrun checks.
+4. Incrementally update only intelligence and graph artifacts affected by changed behavior.
+5. Record completed work in `.changes/`.
+
+Read-only workflows:
+
+- `map-architecture` maps evidence-backed graphs and may update graph-connected context.
+- `analyze-impact` writes an impact report for a proposal or diff.
+- `sync-engineering-intelligence` synchronizes intelligence for an identified change.
+- `review-engineering-change` writes findings without applying fixes.
+
+Only the `engineering-intelligence` implementation workflow is intended to modify product code.
+
+Use `knowledge-base/`, `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/events/`, `.engineering-intelligence/graph/`, `.engineering-intelligence/reports/`, and `.changes/` as the canonical project-intelligence paths. Never invent undocumented implementation facts.

package/templates/canonical/skills/architecture-review-engine/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: architecture-review-engine
+description: Reviews architectural changes and existing design for coupling, scalability, security, maintainability, and migration risk. Use for architecture decisions and high-risk refactors.
+---
+
+# Architecture Review
+
+Analyze domain boundaries, services, dependencies, runtime patterns, deployment, persistence, security, and operational constraints. Ground findings in evidence.
+
+For a substantial review, write or update `knowledge-base/19-architecture-review.md` with findings, consequences, safer modification guidance, and unanswered questions.

package/templates/canonical/skills/change-detection-engine/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: change-detection-engine
+description: Determines analysis scope from a proposed engineering change, working-tree diff, commit range, or explicit changed files. Use before impact analysis, synchronization, or review.
+---
+
+# Change Detection Engine
+
+Accept one of these inputs:
+
+- a proposed change described by the user
+- an existing working-tree diff
+- a supplied commit or commit range
+- explicitly named changed files
+
+Determine mode (`proposal` or `diff`), inspected scope, changed or likely affected paths, and unresolved ambiguity. When the repository is not under git or the target change cannot be identified, ask for the intended change or affected paths instead of assuming.
+
+This capability is analytical only and must not modify product code.

package/templates/canonical/skills/change-history-engine/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: change-history-engine
+description: Records validated engineering work, impacted systems, tests, synchronized documentation, and outstanding risks. Use after initialization and completed engineering changes.
+---
+
+# Change History
+
+Store change records in `.changes/`.
+
+- Initialization creates `CHG-000-initialization.md`.
+- Subsequent changes create the next numbered `CHG-XXX-<summary>.md`.
+
+Include request summary, files or systems affected, related `IMP-*` and `REV-*` reports when present, implementation summary, tests and validation performed, updated graph/intelligence artifacts, and unresolved risk or follow-up.

package/templates/canonical/skills/context-sync-engine/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: context-sync-engine
+description: Maintains compact AI navigation context when modules, services, dependencies, runtime paths, or risk areas change. Use after significant implementation changes.
+---
+
+# Context Synchronization
+
+Maintain `.engineering-intelligence/context/`:
+
+- `module-map.md`
+- `service-map.md`
+- `runtime-map.md`
+- `critical-paths.md`
+- `dangerous-areas.md`
+- `dependency-map.md`
+
+Keep context concise, navigational, and backed by current project paths.
+
+Use the associated impact report and graph updates to revise only affected maps; do not regenerate unrelated navigation context.

package/templates/canonical/skills/deep-project-knowledge-extractor/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: deep-project-knowledge-extractor
+description: Analyzes an existing software repository and produces evidence-based architecture, runtime, API, infrastructure, risk, and onboarding documentation. Use when creating or refreshing the project knowledge base.
+---
+
+# Deep Project Knowledge Extractor
+
+Inspect package/workspace manifests, source entrypoints, dependency boundaries, routes, schemas, middleware, tests, CI and infrastructure. Generate the structured documents in `knowledge-base/`.
+
+Every material statement must be supported by repository evidence. Cite relevant paths in the documents. State `Not detected` or `Unclear from repository evidence` where appropriate.
+
+Required documents:
+
+- `00-project-overview.md` through `14-glossary.md`
+
+Cover repository structure, architecture, runtime flow, APIs, persistence, authentication, frontend, backend, infrastructure, integrations, complex areas, technical debt, onboarding, and glossary.

package/templates/canonical/skills/engineering-change-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: engineering-change-review
+description: Reviews changed implementation, tests, impact analysis, graph consistency, and synchronized project intelligence without applying fixes. Use after engineering changes or before completion.
+---
+
+# Engineering Change Review
+
+Review changed code and tests against the request, impact report, validation evidence, graph artifacts, and synchronized intelligence.
+
+Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with:
+
+- findings first, ordered by severity
+- code and evidence paths
+- regression, validation, graph-staleness, and documentation-staleness risks
+- test gaps and unresolved questions
+- a short reviewed-change summary only after findings
+
+This review capability may write its report. It must not modify product code or auto-fix findings.

package/templates/canonical/skills/engineering-intelligence/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: engineering-intelligence
+description: Executes engineering changes with impact analysis, implementation, tests, validation, and incremental synchronization of project intelligence. Use for feature, bugfix, update, refactor, architecture, infrastructure, or security requests.
+---
+
+# Engineering Intelligence Workflow
+
+Use this workflow for implementation requests after project intelligence has been initialized.
+
+## Procedure
+
+1. Read relevant files from `knowledge-base/`, `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, and `.engineering-intelligence/graph/`. If missing, run the initialization capability first.
+2. Classify the request and write a pre-change `.engineering-intelligence/reports/IMP-XXX-<summary>.md` impact report before editing.
+3. Implement the requested change in the project code.
+4. Add or update relevant tests and execute the appropriate validation available in the project.
+5. Use incremental synchronization to update only affected knowledge-base, memory, context, event, graph, and report artifacts.
+6. Create the next `.changes/CHG-XXX-<summary>.md` record referencing related impact and any review reports.
+7. For high-risk changes, run engineering-change review before final reporting.
+8. Report code changes, tests run, affected systems, synchronized documentation/graph artifacts, and unresolved risks.
+
+Do not claim validation succeeded unless it ran successfully. Do not update unrelated documents merely to regenerate them.

package/templates/canonical/skills/graph-engine/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: graph-engine
+description: Builds and incrementally maintains evidence-backed dependency, service, runtime, and business-flow graph artifacts with a human-readable architecture map. Use during initialization, explicit architecture mapping, or changes that affect relationships.
+---
+
+# Graph Engine
+
+Generate project graph intelligence under `.engineering-intelligence/graph/`:
+
+- `dependency-graph.json`: modules, packages, shared libraries, imports, and dependency relationships
+- `service-graph.json`: deployable services, databases, queues, external integrations, and communication links
+- `runtime-graph.json`: startup, request, job, and event execution paths
+- `business-flow-graph.json`: verified business/user workflows and participating code or services
+- `architecture-map.md`: Mermaid diagrams and human-readable interpretation of the JSON graphs
+
+## Graph JSON Contract
+
+Each JSON graph uses this envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "graphType": "dependency | service | runtime | business-flow",
+  "generatedAt": "<ISO timestamp>",
+  "scope": "<repository/package/scope examined>",
+  "nodes": [
+    {
+      "id": "<stable identifier>",
+      "kind": "<graph-specific kind>",
+      "label": "<human name>",
+      "path": "<repository path when applicable>",
+      "confidence": "verified | inferred | unknown",
+      "evidence": ["<file path or configuration evidence>"]
+    }
+  ],
+  "edges": [
+    {
+      "from": "<node id>",
+      "to": "<node id>",
+      "relation": "<relationship>",
+      "confidence": "verified | inferred | unknown",
+      "evidence": ["<file path or configuration evidence>"]
+    }
+  ],
+  "unknowns": ["<unconfirmed relationship or flow>"]
+}
+```
+
+## Rules
+
+- Keep node IDs stable across incremental updates while the represented element still exists.
+- Never mark an edge `verified` without evidence paths.
+- Distinguish inferred and unknown relationships clearly.
+- Derive Mermaid diagrams in `architecture-map.md` from the JSON graph content.
+- Rebuild all graphs on initialization, explicit mapping, or when structural impact cannot be bounded.
+- For ordinary changes, update only impacted nodes, edges, maps, and connected context documents.
+
+This capability may write intelligence artifacts. It must not modify product code.

package/templates/canonical/skills/impact-analysis-engine/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: impact-analysis-engine
+description: Determines direct and indirect impact of a proposed or implemented change across modules, APIs, schemas, runtime flows, infrastructure, integrations, and tests. Use before implementation and during synchronization.
+---
+
+# Impact Analysis
+
+Determine what can break before changing code. Analyze imports, callers, routes, data schemas, events, configuration, services, infrastructure, and existing tests.
+
+Read `.engineering-intelligence/graph/` when available. If graphs are missing or stale for the assessed scope, invoke `graph-engine` to establish or refresh the necessary graph context.
+
+Write a reusable `.engineering-intelligence/reports/IMP-XXX-<slug>.md` impact report containing:
+
+- mode (`proposal` or `diff`) and inspected scope
+- graph inputs consulted or refreshed
+- directly affected files and systems
+- indirect dependencies and risks
+- required validation and tests
+- documentation, memory, context, event, and graph artifacts affected by the change
+- evidence, unknowns, and an explicit statement that impact analysis did not modify product code

package/templates/canonical/skills/incremental-sync-engine/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: incremental-sync-engine
+description: Synchronizes only intelligence artifacts affected by a completed change or identified diff, including knowledge, memory, context, events, graphs, and reports. Use for explicit synchronization or after implementation.
+---
+
+# Incremental Sync Engine
+
+Read the completed diff, change record, supplied changed scope, and any existing impact report. If no impact report exists for the scope, run impact analysis first and write one under `.engineering-intelligence/reports/`.
+
+Update only affected:
+
+- `knowledge-base/` documentation
+- `.engineering-intelligence/memory/`
+- `.engineering-intelligence/context/`
+- `.engineering-intelligence/events/`
+- `.engineering-intelligence/graph/` JSON graphs and `architecture-map.md`
+- the associated impact report synchronization notes
+
+Use incremental graph changes by default. Require full graph remapping only for broad or unbounded structural changes.
+
+As a standalone synchronization capability, do not write `.changes/CHG-XXX-*` records and do not modify product code.

package/templates/canonical/skills/initialize-engineering-intelligence/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: initialize-engineering-intelligence
+description: Initializes project engineering intelligence by analyzing repository evidence and generating knowledge, context, memory, event guidance, architecture graphs, and an initialization change record. Use when onboarding a repository or when asked to initialize engineering intelligence.
+---
+
+# Initialize Engineering Intelligence
+
+Create a trustworthy project intelligence baseline. Analyze only evidence present in source code, configuration, tests, infrastructure, and existing documentation. Mark unknowns and uncertainties explicitly; never invent architecture, APIs, schemas, or business rules.
+
+## Outputs
+
+Generate:
+
+- `knowledge-base/00-project-overview.md` through `knowledge-base/15-validation-report.md`
+- `.engineering-intelligence/memory/` for durable decisions, rules, patterns, constraints, and technology decisions
+- `.engineering-intelligence/context/` for module, service, runtime, dependency, critical-path, and dangerous-area maps
+- `.engineering-intelligence/events/` for API, schema, auth, feature, and infrastructure change guidance
+- `.engineering-intelligence/graph/` for JSON dependency, service, runtime, and business-flow graphs plus a Mermaid architecture map
+- `.changes/CHG-000-initialization.md`
+
+## Procedure
+
+1. Discover repositories, packages, runtimes, build systems, entrypoints, CI, deployment, environment examples, databases, APIs, auth, and tests.
+2. Trace architecture and critical runtime flows from code evidence.
+3. Write the knowledge base with file-backed evidence and clearly labeled unknowns.
+4. Validate major documentation claims against the project and write `15-validation-report.md`.
+5. Generate compact durable memory and navigation context from validated findings.
+6. Use `graph-engine` to generate a full evidence-backed graph baseline and `architecture-map.md`.
+7. Generate change-event guidance and initialization history.
+8. Report generated artifacts, confidence limits, and areas requiring human confirmation.
+
+This initialization workflow documents and validates the project. It does not implement product changes.

package/templates/canonical/skills/knowledge-base-validator/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: knowledge-base-validator
+description: Validates project knowledge documentation against source and configuration evidence, identifying stale, unsupported, or uncertain claims. Use after initialization or documentation synchronization.
+---
+
+# Knowledge Base Validator
+
+Read `knowledge-base/*.md`, identify significant claims, and verify them against code, config, infrastructure, and tests.
+
+Write `knowledge-base/15-validation-report.md` with:
+
+- supported, partially supported, unsupported, and unclear findings
+- evidence paths
+- confidence and stale-documentation risks
+- areas needing human review
+
+Do not silently rewrite other knowledge documents; update them only as part of an explicit synchronization workflow.

package/templates/canonical/skills/knowledge-sync-engine/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: knowledge-sync-engine
+description: Incrementally synchronizes the project knowledge base after code changes, updating only documents affected by verified behavior changes. Use after implementation or architectural decisions.
+---
+
+# Knowledge Synchronization
+
+Use the persisted impact report and actual diff to update only affected documents:
+
+- API behavior: `knowledge-base/04-api-documentation.md`
+- persistence/schema: `knowledge-base/05-database.md`
+- authentication/authorization: `knowledge-base/06-authentication.md`
+- runtime flow: `knowledge-base/03-runtime-flow.md`
+- architecture: `knowledge-base/02-architecture.md`
+- frontend/backend/infrastructure/integrations: corresponding knowledge documents
+
+Preserve accurate existing detail and attach evidence for changed claims.

package/templates/canonical/skills/memory-sync-engine/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: memory-sync-engine
+description: Maintains durable engineering memory after architecture, business rule, constraint, convention, or technology decisions change. Use only for long-lived knowledge.
+---
+
+# Memory Synchronization
+
+Maintain `.engineering-intelligence/memory/`:
+
+- `architecture-decisions.md`
+- `business-rules.md`
+- `coding-patterns.md`
+- `project-constraints.md`
+- `technology-decisions.md`
+
+Do not store transient implementation notes or unverified assumptions as durable memory.
+
+Use the associated impact report and actual change evidence to decide whether durable memory is affected. Leave memory unchanged when no long-lived decision, rule, constraint, pattern, or technology choice changed.

package/templates/canonical/skills/refactoring-planner/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: refactoring-planner
+description: Plans safe refactors by identifying dependencies, migration steps, validation needs, compatibility risk, and rollback strategy. Use before non-trivial refactors.
+---
+
+# Refactoring Planner
+
+Identify duplicated logic, unsafe coupling, large or fragile areas, migration boundaries, and tests required to preserve behavior.
+
+For significant proposals, write `knowledge-base/18-refactor-plan.md` with motivation, affected areas, migration steps, risk controls, validation, and rollback guidance.

package/templates/canonical/skills/testing-intelligence-engine/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: testing-intelligence-engine
+description: Determines risk-based testing needs for engineering changes and identifies coverage gaps in critical runtime flows. Use during implementation and validation.
+---
+
+# Testing Intelligence
+
+Inspect existing test patterns and identify the smallest sufficient validation for the impacted behavior. Include unit, integration, end-to-end, migration, security, or operational checks when risk requires them.
+
+When documenting broad testing posture, update `knowledge-base/17-testing-strategy.md`. For individual changes, record tests run and remaining gaps in the relevant `.changes/` entry.

package/templates/canonical/workflows/analyze-impact.md

@@ -0,0 +1,13 @@
+---
+description: Analyze the impact of a proposed change or existing diff and write an evidence-backed impact report without changing product code.
+---
+
+# Analyze Impact
+
+Use `change-detection-engine`, `impact-analysis-engine`, and `graph-engine` when graph intelligence is missing or stale.
+
+Analyze the user-supplied proposed change, working-tree diff, commit/range, or explicit changed paths. If the scope is ambiguous, ask for it instead of assuming.
+
+Write `.engineering-intelligence/reports/IMP-XXX-<slug>.md` covering analysis mode and scope, graph inputs, direct and indirect impact, risks, validation needs, intelligence artifacts needing synchronization, evidence, and uncertainties.
+
+This workflow may write intelligence reports or refresh necessary graph context. It must not modify product code.

package/templates/canonical/workflows/engineering-intelligence.md

@@ -0,0 +1,11 @@
+---
+description: Implement an engineering request with impact analysis, tests, validation, and intelligence synchronization.
+---
+
+# Engineering Intelligence
+
+Use the `engineering-intelligence` capability for the user's accompanying request.
+
+Read project intelligence and graph artifacts, write a pre-change `.engineering-intelligence/reports/IMP-XXX-<summary>.md` impact report, implement the requested work, add or update appropriate tests, validate the result, incrementally synchronize affected knowledge/memory/context/event/graph artifacts, and write the next `.changes/CHG-XXX-<summary>.md` entry referencing related reports. Run review responsibility before completion when change risk is high.
+
+Finish with changed code, tests and validation, affected systems, synchronized artifacts and graphs, related reports, and unresolved risks.

package/templates/canonical/workflows/initialize-engineering-intelligence.md

@@ -0,0 +1,11 @@
+---
+description: Initialize evidence-based engineering intelligence for the current project.
+---
+
+# Initialize Engineering Intelligence
+
+Use the `initialize-engineering-intelligence` capability.
+
+Analyze this repository thoroughly without changing product code. Generate `knowledge-base/`, validate it against evidence, generate `.engineering-intelligence/memory/`, `.engineering-intelligence/context/`, `.engineering-intelligence/events/`, and build `.engineering-intelligence/graph/` JSON graphs plus `architecture-map.md`. Write `.changes/CHG-000-initialization.md`.
+
+Do not fabricate details. Mark uncertainty clearly and finish with the created artifacts and human-review items.

package/templates/canonical/workflows/map-architecture.md

@@ -0,0 +1,17 @@
+---
+description: Build or refresh evidence-backed architecture graph intelligence without changing product code.
+---
+
+# Map Architecture
+
+Use the `graph-engine` capability.
+
+Inspect repository evidence and generate or comprehensively refresh:
+
+- `.engineering-intelligence/graph/dependency-graph.json`
+- `.engineering-intelligence/graph/service-graph.json`
+- `.engineering-intelligence/graph/runtime-graph.json`
+- `.engineering-intelligence/graph/business-flow-graph.json`
+- `.engineering-intelligence/graph/architecture-map.md`
+
+Use stable node IDs, evidence-backed confidence labels, explicit unknowns, and Mermaid diagrams. You may update graph-connected navigation context when necessary. Do not modify product code.

package/templates/canonical/workflows/review-engineering-change.md

@@ -0,0 +1,11 @@
+---
+description: Review changed engineering work, tests, graphs, and synchronized intelligence without applying fixes.
+---
+
+# Review Engineering Change
+
+Use `change-detection-engine` and `engineering-change-review`.
+
+Inspect the identified implementation diff or changed scope, associated impact report, test and validation evidence, graph consistency, and documentation/context synchronization.
+
+Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with severity-ordered findings, evidence paths, test gaps, and stale-intelligence risks. Do not modify product code or auto-fix findings.

package/templates/canonical/workflows/sync-engineering-intelligence.md

@@ -0,0 +1,11 @@
+---
+description: Incrementally synchronize intelligence artifacts for an identified change without modifying product code.
+---
+
+# Sync Engineering Intelligence
+
+Use `change-detection-engine`, `impact-analysis-engine`, and `incremental-sync-engine`.
+
+Read the supplied changed scope, diff, or completed change record. Create an impact report first if none exists for that scope. Update only affected knowledge, memory, context, event, graph, and report artifacts.
+
+Standalone synchronization must not create a `.changes/CHG-XXX-*` implementation record and must not modify product code.