feat: zero-config project documentation auto-discovery

.agent/CheatSheet.md

@@ -1,6 +1,6 @@
 # Devran AI Kit — CheatSheet
 
-> **Version**: v4.5.1 | **Quick Reference** for all capabilities
+> **Version**: v4.6.0 | **Quick Reference** for all capabilities
 > **Session**: Start with `/project_status`, end with session-end checklist
 
 ---
@@ -163,7 +163,7 @@
 
 ---
 
-## 🧩 Skills (34)
+## 🧩 Skills (35)
 
 ### Operational (7)
 
@@ -271,7 +271,7 @@
 
 ---
 
-## ⚖️ Governance Rules (9)
+## ⚖️ Governance Rules (10)
 
 | Rule File | Scope |
 |:----------|:------|
@@ -356,7 +356,7 @@
 │
 ├── agents/                  # 23 specialized agents
 ├── commands/                # 37 slash commands
-├── skills/                  # 34 capability extensions
+├── skills/                  # 35 capability extensions
 ├── workflows/               # 22 slash command workflows
 ├── hooks/                   # Event-driven automation
 ├── rules/                   # 9 modular governance rules

.agent/README.md

@@ -26,7 +26,7 @@ This loads your session context and activates the orchestrator.
 │
 ├── agents/                 # 23 specialized agents
 ├── commands/               # 37 slash commands
-├── skills/                 # 34 capability extensions
+├── skills/                 # 35 capability extensions
 ├── workflows/              # 22 slash command workflows
 ├── hooks/                  # Event-driven automation
 ├── rules/                  # Modular governance

.agent/commands/help.md

@@ -13,7 +13,7 @@ Your complete guide to the Devran AI Kit. Type `/help` for a quick overview, or
 /help commands         # All 37 slash commands with descriptions
 /help workflows        # All 22 workflows with descriptions
 /help agents           # All 23 AI agents with domains
-/help skills           # All 34 skill modules
+/help skills           # All 35 skill modules
 /help rules            # Governance rules
 /help checklists       # Quality gate checklists
 /help cli              # Terminal CLI commands (kit)
@@ -24,15 +24,15 @@ Your complete guide to the Devran AI Kit. Type `/help` for a quick overview, or
 
 ## Quick Overview
 
-**Devran AI Kit v4.5.1** — Trust-Grade AI Development Framework
+**Devran AI Kit v4.6.0** — Trust-Grade AI Development Framework
 
 | Category | Count | Description |
 |:---------|:------|:------------|
 | ⌨️ Commands | 37 | Slash commands for every development task |
 | 🔄 Workflows | 22 | Multi-step development lifecycles |
 | 🤖 Agents | 23 | Specialized AI roles for delegation |
-| 🛠️ Skills | 34 | Domain knowledge modules |
-| ⚖️ Rules | 9 | Modular governance constraints |
+| 🛠️ Skills | 35 | Domain knowledge modules |
+| ⚖️ Rules | 10 | Modular governance constraints |
 | ✅ Checklists | 4 | Quality gate checklists |
 | ⚙️ Runtime | 33 | Engine modules (governance, reputation, self-healing) |
 
@@ -189,7 +189,7 @@ Agents are specialized AI roles. They are automatically activated based on task
 
 ---
 
-## Skills (34)
+## Skills (35)
 
 Skills are domain knowledge modules that agents use. They are loaded automatically based on task context.
 
@@ -210,7 +210,7 @@ Skills are domain knowledge modules that agents use. They are loaded automatical
 
 ---
 
-## Rules (9)
+## Rules (10)
 
 Rules are modular governance constraints that all agents must follow.
 
@@ -225,6 +225,7 @@ Rules are modular governance constraints that all agents must follow.
 | `quality-gate` | Pre-task validation and quality standards |
 | `architecture` | System design patterns and ADR governance |
 | `agent-upgrade-policy` | Framework upgrade preservation rules |
+| `workflow-standards` | Artifact discipline, evidence standards, governance |
 
 ---
 

.agent/engine/loading-rules.json

@@ -1,5 +1,13 @@
 {
-  "schemaVersion": "1.0.0",
+  "schemaVersion": "1.1.0",
+  "projectDocDiscovery": {
+    "enabled": true,
+    "maxDocs": 8,
+    "scanDepth": 3,
+    "maxFiles": 200,
+    "domainBoost": 2,
+    "description": "Auto-discovers project docs/ and includes domain-relevant docs in load plan. Zero-config."
+  },
   "defaultLoad": [
     "rules.md",
     "manifest.json",

.agent/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "kitVersion": "4.5.1",
+  "kitVersion": "4.6.0",
   "lastAuditedAt": null,
   "description": "Devran AI Kit — Trust-Grade AI Development Framework",
   "repository": "https://github.com/devran-ai/kit",
@@ -130,7 +130,7 @@
       "directory": "commands/"
     },
     "skills": {
-      "count": 34,
+      "count": 35,
       "items": [
         {
           "name": "api-patterns",
@@ -236,6 +236,10 @@
           "name": "production-readiness",
           "directory": "skills/production-readiness/"
         },
+        {
+          "name": "project-docs-discovery",
+          "directory": "skills/project-docs-discovery/"
+        },
         {
           "name": "security-practices",
           "directory": "skills/security-practices/"

.agent/session-context.md

@@ -32,7 +32,7 @@
 
 **Branch**: —  
 **Repository**: —  
-**Framework**: Devran AI Kit v4.5.1
+**Framework**: Devran AI Kit v4.6.0
 
 ### Key File Locations
 

.agent/skills/README.md

@@ -1,7 +1,7 @@
 # Devran AI Kit — Skills
 
 > **Purpose**: Workflow definitions and domain knowledge extensions
-> **Count**: 34 Skills (7 Operational + 4 Orchestration + 14 Domain + 9 Development)
+> **Count**: 35 Skills (8 Operational + 4 Orchestration + 14 Domain + 9 Development)
 
 ---
 

.agent/skills/project-docs-discovery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: project-docs-discovery
+description: Auto-discover and consult project-specific documentation before development tasks.
+version: 1.0.0
+triggers: [review, plan, create, enhance, debug, design, architecture, compliance, screen, component]
+---
+
+# Project Docs Discovery
+
+> **Purpose**: Automatically find and reference project-specific documentation so workflows produce output aligned with the project's design system, architecture, and guidelines — without manual prompting.
+
+---
+
+## Discovery Algorithm
+
+At the start of any workflow that modifies or evaluates code, execute these steps:
+
+### Step 1: Scan for documentation
+
+Use Glob to find project docs:
+
+```
+Glob("docs/**/*.md")
+```
+
+Also check project root for: `ARCHITECTURE.md`, `COMPLIANCE.md`, `DESIGN.md`, `SECURITY.md`
+
+If no results found — **skip remaining steps silently**. Do not mention missing docs.
+
+### Step 2: Classify by relevance to current task
+
+| Task Domain | Priority Docs | Why |
+|---|---|---|
+| Frontend/UI | `docs/design-system/`, `docs/screens/`, `SCREENS-INVENTORY.md` | Component consistency, token compliance |
+| Security | `COMPLIANCE.md`, `docs/design-system/accessibility.md` | Regulatory and a11y requirements |
+| Planning | `docs/epics/`, `ROADMAP.md`, `SPRINT*.md` | Feature scope and priorities |
+| Backend/API | `docs/api-docs/`, `ARCHITECTURE.md` | API contracts and system design |
+| Architecture | `ARCHITECTURE.md`, `docs/architecture/` | System design decisions |
+| Any task | `ARCHITECTURE.md` | Always relevant for system context |
+
+### Step 3: Read top 3-5 most relevant docs (context-aware)
+
+Budget rules to preserve context window:
+
+- **Design system files** (tokens, components, patterns): read **FULLY** — they define hard constraints
+- **Architecture docs** (>200 lines): read **first 100 lines** for system overview
+- **Epic/screen specs**: read **only the section** relevant to the current task
+- **Total context budget**: ~800 lines max across all discovered docs
+
+Skip directories:
+- `docs/archives/` — historical only
+- `docs/research/` — exploratory only
+
+### Step 4: Reference in output
+
+Cite specific constraints from discovered docs in your output.
+
+Examples:
+- "Per `design-system/tokens.md`, spacing uses 4px base unit"
+- "Per `ARCHITECTURE.md`, data layer uses Repository pattern"
+- "Per `COMPLIANCE.md`, PII must be encrypted at rest"
+
+### Step 5: Graceful no-docs handling
+
+If Glob returns zero results and no root-level doc files exist, skip this discovery entirely. Do not mention missing docs to the user. Not all projects have a `docs/` directory.
+
+---
+
+## When NOT to discover
+
+- `/deploy` — deployment procedures, not code evaluation
+- `/upgrade` — framework upgrade, not project code
+- `/pr-merge` — merge mechanics, not code analysis
+- Any project with no `docs/` directory — auto-skipped

.agent/workflows/create.md

@@ -3,7 +3,7 @@ description: Create new features, components, or modules from scratch.
 args: component or feature name
 version: 2.1.0
 sdlc-phase: build
-skills: [app-builder, clean-code]
+skills: [app-builder, clean-code, project-docs-discovery]
 commit-types: [feat]
 ---
 
@@ -18,7 +18,7 @@ commit-types: [feat]
 
 ## Critical Rules
 
-1. Follow existing patterns — scan codebase before writing
+1. Follow existing patterns — scan codebase and project design system docs before writing
 2. No orphan code — every file must be imported/referenced/routed
 3. Tests required for all new features
 4. Stack-agnostic detection from config files

.agent/workflows/debug.md

@@ -3,7 +3,7 @@ description: Systematic debugging workflow. Activates DEBUG mode for problem inv
 args: error or issue description
 version: 2.1.0
 sdlc-phase: reactive
-skills: [debugging-strategies]
+skills: [debugging-strategies, project-docs-discovery]
 commit-types: [fix]
 ---
 
@@ -21,7 +21,7 @@ commit-types: [fix]
 1. Root cause required — never fix without understanding why
 2. No guessing — form hypotheses, test systematically
 3. Prevention mandatory — every fix includes recurrence prevention
-4. Preserve evidence before changing anything
+4. Preserve evidence before changing anything — check project `ARCHITECTURE.md` for system design context
 5. Minimal changes — fix only what's broken
 
 ---

.agent/workflows/enhance.md

@@ -3,7 +3,7 @@ description: Add or update features in existing application. Iterative developme
 args: feature description
 version: 2.1.0
 sdlc-phase: build
-skills: [clean-code, testing-patterns]
+skills: [clean-code, testing-patterns, project-docs-discovery]
 commit-types: [feat, refactor]
 ---
 
@@ -22,7 +22,7 @@ commit-types: [feat, refactor]
 2. Regression check mandatory after every change
 3. User approval for changes affecting >5 files
 4. Incremental approach — small, verifiable changes
-5. Follow existing conventions
+5. Follow existing conventions — consult project architecture and design system docs before modifying
 6. Document user-facing changes
 
 ---

.agent/workflows/plan.md

@@ -4,7 +4,7 @@ args: feature or task description
 version: 2.2.0
 sdlc-phase: plan
 agents: [planner]
-skills: [plan-writing, brainstorming, plan-validation]
+skills: [plan-writing, brainstorming, plan-validation, project-docs-discovery]
 commit-types: [docs]
 ---
 
@@ -38,6 +38,8 @@ commit-types: [docs]
 // turbo
 2. **Explore Codebase** — scan structure, identify relevant files, patterns, dependencies.
 
+2.5. **Consult Project Docs** — scan `docs/` for architecture, design system, and guidelines. Reference discovered constraints in plan sections. If no project docs found, skip.
+
 3. **Create Plan**
    - Consult mandatory rules (security, testing, coding-style, documentation, git-workflow)
    - Classify task: Trivial (1-2 files), Medium (3-10), Large (10+)

.agent/workflows/pr-review.md

@@ -3,7 +3,7 @@ description: Multi-perspective PR review covering hygiene, branch strategy, code
 args: "PR #"
 version: 1.1.0
 sdlc-phase: verify
-skills: [pr-toolkit, verification-loop]
+skills: [pr-toolkit, verification-loop, project-docs-discovery]
 commit-types: []
 ---
 
@@ -91,11 +91,16 @@ gh pr checks <number> --repo <owner/repo>
 - Validate target branch per strategy rules
 - Check branch naming convention
 
+### Step 5.5: Project Docs Cross-Reference
+
+Scan `docs/` for design system, architecture, and compliance docs. In Step 6, cross-reference code changes against discovered project guidelines and constraints. If no project docs found, skip.
+
 ### Step 6: Multi-Perspective Code Review
 
 Read each changed file. For every finding include: `file:line`, quoted code, impact explanation, concrete fix.
 
 **Cross-file consistency**: verify counts, references, categorizations match across related files.
+**Project docs consistency**: verify changes align with discovered design system, architecture, and compliance docs.
 
 **6a. Code Quality** — function size (>50 lines), file size (>800 lines), nesting (>4 levels), error handling, debug artifacts, naming, immutability
 

.agent/workflows/quality-gate.md

@@ -3,7 +3,7 @@ description: Pre-task research and validation protocol. Market research, gap ana
 args: feature name
 version: 2.1.0
 sdlc-phase: discover
-skills: [brainstorming]
+skills: [brainstorming, project-docs-discovery]
 commit-types: [docs, chore]
 ---
 
@@ -18,7 +18,7 @@ commit-types: [docs, chore]
 
 ## Critical Rules
 
-1. No implementation without validated research
+1. No implementation without validated research — review project `ROADMAP.md` and architecture docs for alignment
 2. All claims backed by market data or competitor analysis
 3. Ethics gate — privacy, bias, automation risks evaluated
 4. Approval required before proceeding

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to Devran AI Kit will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.6.0] — 2026-03-28
+
+### Added
+
+- **Project Documentation Auto-Discovery** — Zero-config discovery of project-specific documentation (design system, architecture, screen specs, compliance). Workflows automatically find and reference project docs without manual prompting.
+  - New runtime module: `lib/doc-discovery.js` (300 LOC) — scans `docs/`, classifies by 14 patterns, ranks by domain relevance, budget-constrained (max 8 docs)
+  - New skill: `project-docs-discovery` — instructs LLM to scan and read relevant project docs during workflows
+  - Loading engine integration: `getLoadPlan()` returns `projectDocs[]` for CLI/tooling
+  - 6 workflows updated: `/plan`, `/pr-review`, `/create`, `/enhance`, `/debug`, `/quality-gate`
+  - Security hardened: path canonicalization (CWE-22), `realpathSync` symlink detection, 25-dir skip list, numeric input validation
+- Skills: 34 → 35 (`project-docs-discovery` added)
+- Tests: 499 → 533 (34 new doc-discovery tests, 39 test files)
+- **GitHub Flow** — Established PR-based workflow with branch protection on `main`. Documented in CONTRIBUTING.md.
+- **Telegram Menu Guard** — Fixed private chat menu overwrite. Guard now pushes to `all_private_chats` scope (not per-chat), with health check retry at +15s.
+
+### Changed
+
+- **Documentation alignment** — All 26 doc/config files synced to manifest SSOT (skills 35, tests 533, rules 10)
+
+---
+
 ## [4.5.1] — 2026-03-27
 
 ### Changed