engineering-intelligence 0.2.0 → 0.3.0

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

@@ -1,19 +1,126 @@
 ---
 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.
+version: 3.0.0
 ---
 
 # Context Synchronization
 
-Maintain `.engineering-intelligence/context/`:
+Maintain concise, navigational context maps optimized for AI agent use. Context maps help agents quickly find the right file, module, or service — not replace the knowledge base.
 
-- `module-map.md`
-- `service-map.md`
-- `runtime-map.md`
-- `critical-paths.md`
-- `dangerous-areas.md`
-- `dependency-map.md`
+## Inputs
 
-Keep context concise, navigational, and backed by current project paths.
+- Impact report and graph updates
+- Current `.engineering-intelligence/context/` documents
 
-Use the associated impact report and graph updates to revise only affected maps; do not regenerate unrelated navigation context.
+## Context Maps
+
+Maintain these maps in `.engineering-intelligence/context/`:
+
+### `module-map.md` — Module Navigation
+
+```markdown
+# Module Map
+
+| Module | Path | Responsibility | Key Files |
+|---|---|---|---|
+| auth | src/auth/ | Authentication, JWT, RBAC | middleware.ts, jwt.ts |
+| api | src/routes/ | REST endpoint handlers | users.ts, products.ts |
+```
+
+### `service-map.md` — Service Topology
+
+```markdown
+# Service Map
+
+| Service | Port | Protocol | Dependencies | Health Check |
+|---|---|---|---|---|
+| api-server | 3000 | HTTP | postgres, redis | /health |
+| worker | — | — | rabbitmq, postgres | — |
+```
+
+### `runtime-map.md` — Request Flows
+
+```markdown
+# Runtime Map
+
+## HTTP Request Flow
+Entry → CORS → Auth → Rate Limit → Router → Handler → Response
+
+## Background Job Flow
+Queue → Worker → Process → DB Write → Notify
+```
+
+### `critical-paths.md` — Revenue & Safety Critical Flows
+
+```markdown
+# Critical Paths
+
+| Flow | Entry Point | Risk | Last Verified |
+|---|---|---|---|
+| Payment processing | POST /api/checkout | High | CHG-005 |
+| User registration | POST /api/auth/register | Medium | CHG-003 |
+```
+
+### `dangerous-areas.md` — Fragile & Risky Code
+
+```markdown
+# Dangerous Areas
+
+| Area | Path | Risk | Reason |
+|---|---|---|---|
+| Legacy auth | src/auth/legacy.ts | High | No tests, race conditions |
+| Payment retry | src/payments/retry.ts | High | Complex state machine |
+```
+
+### `dependency-map.md` — External Dependencies
+
+```markdown
+# Dependency Map
+
+| Dependency | Version | Consumers | Risk |
+|---|---|---|---|
+| express | 4.18.x | api-server | Low — stable |
+| stripe | 12.x | payments module | Medium — breaking changes |
+```
+
+## Procedure
+
+1. **Check Impact** — Review the impact report and graph updates. Identify which context maps are affected.
+
+2. **Update Affected Maps** — For each affected map:
+   - Update specific entries, not the entire map
+   - Add new entries for new modules/services/paths
+   - Remove entries for deleted modules/services
+   - Update paths and descriptions for renamed elements
+
+3. **Preserve Conciseness** — Each map should be:
+   - Under 150 lines
+   - Table-formatted where possible
+   - Navigational (paths and quick descriptions), not explanatory
+   - Optimized for AI agent context windows
+
+4. **Verify Accuracy** — Cross-check updated maps against:
+   - Current `.engineering-intelligence/graph/` data
+   - Actual file system paths (do they still exist?)
+
+## Rules
+
+- Keep context concise and navigational — not a knowledge-base duplicate
+- Use tables over prose wherever possible
+- Update only affected maps from the impact report
+- Do not regenerate unrelated context
+- Maps must reflect actual file system state (no phantom paths)
+
+## Quality Gates
+
+- [ ] Each map is under 150 lines
+- [ ] Updated entries reference real, existing paths
+- [ ] Only impact-affected maps were modified
+- [ ] Table format used where appropriate
+
+## Cross-References
+
+- Depends on: `impact-analysis-engine` (identifies affected maps), `graph-engine` (provides topology data)
+- Used by: `incremental-sync-engine`, `engineering-intelligence-skill`
+- Consumed by: All agents (for navigation)

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

@@ -1,16 +1,182 @@
 ---
 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.
+version: 3.0.0
 ---
 
 # 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/`.
+Produce comprehensive, evidence-backed project documentation by systematic repository analysis. Every material claim must cite a source file path. Silence is never acceptable — use `**Not detected**` for absent features.
 
-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.
+## Inputs
 
-Required documents:
+- Repository root path
+- Optional: scope constraints (specific package, service, or directory)
 
-- `00-project-overview.md` through `14-glossary.md`
+## Discovery Checklist
 
-Cover repository structure, architecture, runtime flow, APIs, persistence, authentication, frontend, backend, infrastructure, integrations, complex areas, technical debt, onboarding, and glossary.
+Scan the repository systematically for each category:
+
+| Category | What to Look For |
+|---|---|
+| **Package Management** | `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, workspace configs |
+| **Build System** | `Makefile`, `webpack.config.*`, `vite.config.*`, `tsconfig.json`, `build.gradle` |
+| **Entrypoints** | `main.*`, `index.*`, `app.*`, `server.*`, bin scripts |
+| **Routing** | Express/Koa/Fastify routes, Next.js pages/app dirs, API gateways |
+| **Database** | Migration dirs, schema files, ORM configs, seed scripts |
+| **Auth** | Passport/Auth0/JWT configs, middleware, RBAC definitions |
+| **CI/CD** | `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `Dockerfile` |
+| **Infrastructure** | `docker-compose.yml`, `terraform/`, `k8s/`, `serverless.yml` |
+| **Tests** | `test/`, `__tests__/`, `spec/`, `*.test.*`, `*.spec.*`, test configs |
+| **Environment** | `.env.example`, `.env.sample`, env validation schemas |
+| **Documentation** | `README.md`, `docs/`, `CHANGELOG.md`, `CONTRIBUTING.md` |
+
+## Output Specification
+
+Generate each document in `knowledge-base/` with this structure:
+
+```markdown
+# <Document Title>
+
+<One-paragraph executive summary>
+
+## <Section>
+
+<Content with inline evidence citations>
+
+(evidence: path/to/file:L42-L58)
+
+## Unknowns & Uncertainties
+
+- <what is unclear and why>
+```
+
+### Required Documents
+
+#### `00-project-overview.md`
+- Project name, description, primary purpose
+- Technology stack (languages, frameworks, major libraries)
+- Repository type (monorepo, polyrepo, single-package)
+- High-level architecture summary (1 paragraph)
+- Key entry points and how to run the project
+
+#### `01-repository-structure.md`
+- Annotated directory tree (top 2-3 levels)
+- Package/workspace boundaries
+- Build output directories
+- Generated vs authored code distinction
+
+#### `02-architecture.md`
+- Architectural pattern (monolith, microservices, serverless, modular monolith)
+- Layer definitions (presentation, business, data, infrastructure)
+- Module/package boundaries and their responsibilities
+- Communication patterns (HTTP, gRPC, events, queues)
+- Dependency direction rules
+
+#### `03-runtime-flow.md`
+- Application startup sequence
+- Request lifecycle (from entry to response)
+- Background job / worker flows
+- Shutdown / graceful termination
+- Async processing patterns
+
+#### `04-api-documentation.md`
+- REST endpoints: method, path, auth, request/response shapes
+- GraphQL schemas and resolvers
+- WebSocket channels
+- RPC interfaces
+- API versioning strategy
+
+#### `05-database.md`
+- Database engine(s) and connection configuration
+- Schema overview (tables/collections, key relationships)
+- Migration strategy and tooling
+- Caching layers (Redis, Memcached, in-memory)
+- Data access patterns (repository, active record, query builder)
+
+#### `06-authentication.md`
+- Auth provider and strategy (JWT, session, OAuth, SAML)
+- Login/registration flows
+- Token lifecycle and refresh
+- Role/permission model (RBAC, ABAC)
+- Protected route/middleware patterns
+
+#### `07-frontend.md`
+- UI framework and version
+- Routing strategy (client-side, SSR, SSG)
+- State management approach
+- Component architecture and patterns
+- Styling approach (CSS modules, Tailwind, styled-components)
+- Build and bundling pipeline
+
+#### `08-backend.md`
+- Server framework and version
+- Middleware stack (ordered list)
+- Service/controller pattern
+- Error handling strategy
+- Logging and observability
+
+#### `09-infrastructure.md`
+- Hosting/cloud provider
+- Container orchestration
+- CI/CD pipeline stages
+- Environment management (dev, staging, prod)
+- Secrets management
+- Monitoring and alerting
+
+#### `10-integrations.md`
+- Third-party API integrations
+- Payment processors, email services, SMS
+- Analytics and tracking
+- External data sources
+- Webhook consumers/producers
+
+#### `11-complex-areas.md`
+- High cyclomatic complexity modules
+- Business logic with many edge cases
+- Code with subtle race conditions or timing dependencies
+- Areas with heavy tech debt affecting reliability
+
+#### `12-technical-debt.md`
+- Deprecated patterns still in use
+- Missing test coverage in critical paths
+- Known performance bottlenecks
+- Planned but incomplete migrations
+- Security improvements needed
+
+#### `13-onboarding.md`
+- Prerequisites (tools, accounts, access)
+- Setup steps (clone, install, configure, run)
+- Development workflow (branch, test, PR)
+- Common tasks and commands
+- Troubleshooting common issues
+
+#### `14-glossary.md`
+- Domain-specific terms with definitions
+- Abbreviations and acronyms
+- Naming conventions used in the codebase
+
+#### `15-validation-report.md`
+- Generated by `knowledge-base-validator` after extraction
+
+## Evidence Rules
+
+1. Every architectural claim must cite at least one source file
+2. Use the format: `(evidence: relative/path/to/file:L<line>)` or `(evidence: relative/path/to/file)`
+3. When evidence is indirect (inferred from patterns), use: `(inferred from: path/to/file)`
+4. When no evidence exists: `**Not detected** — no relevant configuration or code found`
+5. When evidence is ambiguous: `**Unclear from evidence** — [explanation of ambiguity]`
+
+## Quality Gates
+
+- [ ] All 16 documents generated (00 through 15)
+- [ ] Every document has an executive summary paragraph
+- [ ] Every material claim has an evidence citation
+- [ ] Absent features use `**Not detected**` — not silence
+- [ ] Ambiguous areas use `**Unclear from evidence**`
+- [ ] No invented implementation details
+
+## Cross-References
+
+- Used by: `initialize-intelligence-skill`
+- Feeds into: `knowledge-base-validator`, all sync engines

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

@@ -1,18 +1,154 @@
 ---
 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.
+description: Reviews engineering changes for correctness, test coverage, architecture alignment, graph consistency, and documentation accuracy. Use after implementation to validate quality before completion.
+version: 3.0.0
 ---
 
 # Engineering Change Review
 
-Review changed code and tests against the request, impact report, validation evidence, graph artifacts, and synchronized intelligence.
+Review completed engineering work for correctness, completeness, and alignment with project standards. Produce a structured review report with severity-ordered findings.
 
-Write `.engineering-intelligence/reports/REV-XXX-<slug>.md` with:
+## Inputs
 
-- 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
+- Implementation diff or changed scope
+- Impact report (`.engineering-intelligence/reports/IMP-XXX-*.md`)
+- Test and validation evidence
+- Updated graph and intelligence artifacts
 
-This review capability may write its report. It must not modify product code or auto-fix findings.
+## Review Dimensions
+
+### 1. Implementation Correctness
+
+| Check | What to Verify |
+|---|---|
+| Request fulfillment | Does the implementation address the original request? |
+| Logic correctness | Are algorithms and business logic correct? |
+| Edge cases | Are boundary conditions handled? |
+| Error handling | Are errors caught, logged, and reported appropriately? |
+| Resource management | Are connections, files, and memory properly managed? |
+| Concurrency safety | Are shared resources properly synchronized? |
+
+### 2. Test Coverage
+
+| Check | What to Verify |
+|---|---|
+| Happy path | Is the expected behavior tested? |
+| Error path | Are error scenarios tested? |
+| Regression | Does a test prevent the original issue from recurring (bugfix)? |
+| Boundary | Are edge cases and limits tested? |
+| Execution | Were tests actually run? (Not just written) |
+| Results | Did all tests pass? Are failures explained? |
+
+### 3. Architecture Alignment
+
+| Check | What to Verify |
+|---|---|
+| Boundary respect | Does the change respect module/service boundaries? |
+| Pattern compliance | Does it follow established patterns from memory? |
+| Dependency direction | Are dependencies flowing in the correct direction? |
+| Abstraction level | Is the code at the appropriate abstraction level? |
+
+### 4. Graph Consistency
+
+| Check | What to Verify |
+|---|---|
+| Node updates | Are new modules/services reflected in graphs? |
+| Edge updates | Are new dependencies/relationships reflected? |
+| Stale entries | Were removed elements cleaned from graphs? |
+| Map alignment | Does architecture-map.md reflect JSON graph changes? |
+
+### 5. Documentation Accuracy
+
+| Check | What to Verify |
+|---|---|
+| Knowledge sync | Were affected knowledge docs updated? |
+| Memory sync | Were durable decisions captured if needed? |
+| Context sync | Were navigation maps updated? |
+| Change record | Does the CHG record accurately reflect the work? |
+| Impact report | Was the impact report referenced correctly? |
+
+## Finding Severity Scale
+
+| Severity | Symbol | Meaning | Action Required |
+|---|---|---|---|
+| Blocker | 🔴 | Breaks functionality or introduces security risk | Must fix before completion |
+| Major | 🟠 | Significant issue but not immediately breaking | Should fix before completion |
+| Minor | 🟡 | Code quality or style issue | Fix when convenient |
+| Suggestion | 🔵 | Optional improvement | Consider for future |
+| Positive | 🟢 | Good practice or improvement observed | No action needed |
+
+## Procedure
+
+1. **Read Context** — Load the impact report, implementation diff, and test results.
+2. **Review Each Dimension** — Walk through all five review dimensions above.
+3. **Score Findings** — Assign severity to each finding.
+4. **Check Intelligence** — Verify graph, knowledge, memory, and context were appropriately synced.
+5. **Write Report** — Generate the review report.
+
+## Output Format
+
+Write `.engineering-intelligence/reports/REV-XXX-<slug>.md`:
+
+```markdown
+# REV-XXX: <summary>
+
+## Meta
+- Date: <ISO timestamp>
+- Related: IMP-XXX, CHG-XXX
+- Scope: <what was reviewed>
+
+## Summary
+- Total findings: X
+- 🔴 Blocker: Y | 🟠 Major: Z | 🟡 Minor: W | 🔵 Suggestion: V
+
+## Verdict
+- [ ] ✅ Approved — No blocking issues
+- [ ] ⚠️ Approved with findings — Non-blocking issues noted
+- [ ] ❌ Changes required — Blocking issues must be addressed
+
+## Findings
+
+### 🔴 [Finding Title]
+- **Dimension**: Implementation / Testing / Architecture / Graph / Documentation
+- **Location**: <file:line or artifact path>
+- **Description**: <what was found>
+- **Evidence**: <code reference or comparison>
+- **Recommendation**: <how to fix>
+
+### 🟢 [Positive Finding]
+- **Description**: <good practice observed>
+
+## Test Gaps
+- <untested areas that should be tested>
+
+## Intelligence Sync Status
+| Artifact | Status | Notes |
+|---|---|---|
+| knowledge-base/ | ✅ Synced | API docs updated |
+| graph/ | ⚠️ Partial | Missing new service node |
+
+## Stale Intelligence Risks
+- <areas where docs may drift from code>
+```
+
+## Rules
+
+- Review is read-only — do not apply fixes during a review-only workflow
+- Be honest about gaps and risks — sugar-coating helps nobody
+- Include positive findings alongside issues — balanced review
+- All findings must cite specific evidence (file paths, code references)
+- If tests were not actually run, flag it as a major finding
+
+## Quality Gates
+
+- [ ] All five review dimensions were evaluated
+- [ ] Each finding has severity, location, and evidence
+- [ ] Test execution was verified (not assumed)
+- [ ] Intelligence sync status was checked
+- [ ] Report includes verdict (approved/changes required)
+
+## Cross-References
+
+- Depends on: `change-detection-engine` (identifies what to review)
+- Used by: `engineering-intelligence-skill` (high-risk review gate), `review-engineering-change` workflow
+- Reads: Impact reports, change records, graph artifacts

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

@@ -0,0 +1,168 @@
+---
+name: engineering-intelligence-skill
+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.
+version: 3.0.0
+---
+
+# Engineering Intelligence Implementation
+
+The core implementation skill for engineering work. Use after project intelligence has been initialized.
+
+## Inputs
+
+- User request describing the desired change
+- Repository with initialized intelligence (`knowledge-base/`, `.engineering-intelligence/`)
+
+## Request Classification
+
+Classify the incoming request before starting:
+
+| Type | Description | Risk Level |
+|---|---|---|
+| `feature` | New user-facing functionality | Medium–High |
+| `bugfix` | Correction of incorrect behavior | Low–Medium |
+| `update` | Dependency, config, or version updates | Low–Medium |
+| `refactor` | Structural improvement without behavior change | Medium |
+| `architecture` | Boundary, layer, or pattern changes | High |
+| `infrastructure` | CI, deployment, environment changes | Medium–High |
+| `security` | Auth, permissions, vulnerability fixes | High |
+| `documentation` | Knowledge-only changes (no product code) | Low |
+
+## Procedure
+
+### 1. Pre-Flight: Read Intelligence
+
+Read these artifacts and identify relevant context:
+- `knowledge-base/` — architecture, APIs, runtime flow relevant to the change
+- `.engineering-intelligence/memory/` — decisions, constraints, patterns that apply
+- `.engineering-intelligence/context/` — module map, critical paths, dangerous areas near the change
+- `.engineering-intelligence/graph/` — dependency and service relationships
+
+**If intelligence is missing or stale**: Run `initialize-intelligence-skill` first.
+
+### 2. Impact Analysis: Write Report
+
+Before any code edit, write `.engineering-intelligence/reports/IMP-XXX-<summary>.md`:
+
+```markdown
+# IMP-XXX: <summary>
+
+## Classification
+- Type: <feature|bugfix|update|refactor|architecture|infrastructure|security>
+- Risk: <low|medium|high|critical>
+- Scope: <files and modules affected>
+
+## Analysis
+- Mode: <proposal|diff>
+- Graph inputs consulted: <list>
+- Directly affected: <files, modules, services>
+- Indirectly affected: <downstream consumers, dependent services>
+- Risk factors: <breaking changes, data migration, auth impact>
+
+## Validation Requirements
+- <test types needed>
+- <manual verification needed>
+
+## Intelligence Artifacts Affected
+- <knowledge docs, memory entries, context maps, graph nodes>
+
+## Evidence
+- <file paths supporting each claim>
+
+## Unknowns
+- <areas where impact is uncertain>
+```
+
+### 3. Implement the Change
+
+- Edit only the files necessary for the request
+- Follow existing coding patterns from `.engineering-intelligence/memory/coding-patterns.md`
+- Respect architectural boundaries from `.engineering-intelligence/memory/architecture-decisions.md`
+- Consult `dangerous-areas.md` before modifying flagged code
+
+### 4. Add/Update Tests
+
+- Add tests proportional to the change risk level
+- For `bugfix`: add a regression test reproducing the original issue
+- For `feature`: add unit tests and integration tests for the new behavior
+- For `architecture`/`security`: add boundary and negative-path tests
+- Run the project's test suite and record actual results
+
+### 5. Validate
+
+- Run linters, type checks, and test suites available in the project
+- **Never claim validation passed unless it actually ran and passed**
+- Record partial or failed validation honestly
+
+### 6. Incremental Sync
+
+Use `incremental-sync-engine` to update only affected artifacts:
+- Knowledge docs reflecting changed behavior
+- Memory entries if decisions/patterns changed
+- Context maps if module/service topology changed
+- Graph nodes/edges if dependencies or services changed
+- Event guidance if API/schema/auth contracts changed
+
+### 7. Record Change
+
+Create `.changes/CHG-XXX-<summary>.md`:
+
+```markdown
+# CHG-XXX: <summary>
+
+## Request
+<original user request>
+
+## Classification
+- Type: <type> | Risk: <level>
+
+## Implementation Summary
+<what was changed and why>
+
+## Files Changed
+- <path> — <description of change>
+
+## Tests
+- <tests added/modified>
+- <test results: passed/failed/skipped>
+
+## Related Reports
+- IMP-XXX: <link to impact report>
+- REV-XXX: <link to review report, if applicable>
+
+## Synchronized Artifacts
+- <list of updated intelligence artifacts>
+
+## Unresolved Risks
+- <any remaining concerns>
+```
+
+### 8. High-Risk Review Gate
+
+For changes classified as `high` or `critical` risk:
+- Run `engineering-change-review` before final reporting
+- Address any blocking findings before marking complete
+
+### 9. Report
+
+Summarize to the user:
+- Code changes made (files, lines)
+- Tests run and results
+- Affected systems and services
+- Synchronized intelligence artifacts
+- Unresolved risks or follow-ups
+
+## Quality Gates
+
+- [ ] Impact report written before any code edit
+- [ ] All changed behavior has corresponding test coverage
+- [ ] Validation was actually executed (not just claimed)
+- [ ] Only affected intelligence artifacts were updated
+- [ ] Change record references the correct impact report
+- [ ] High-risk changes went through review gate
+
+## Cross-References
+
+- Depends on: `initialize-intelligence-skill` (prerequisite), `change-detection-engine`, `impact-analysis-engine`, `graph-engine`
+- Uses during execution: `testing-intelligence-engine`, `incremental-sync-engine`, `change-history-engine`
+- Optional: `engineering-change-review` (for high-risk), `refactoring-planner` (for refactors)