atabey 0.0.1

package/src/shared/constants.ts

@@ -0,0 +1,218 @@
+/**
+ * Agent Atabey — Single Source of Truth for framework constants.
+ * Import from here instead of hardcoding paths, phases, or directory names.
+ */
+
+// ─── Framework identity ───────────────────────────────────────────────────────
+
+export const FRAMEWORK = {
+    NAME: "Agent Atabey",
+    CORE_DIR: ".atabey",
+    UNIFIED_HUB_DIR: ".agents",
+    CONSTITUTION_FILE: "ATABEY.md",
+    DEFAULT_TRACE_ID: "T-000",
+    DEFAULT_PHASE: "PHASE_0",
+    DEFAULT_MANAGER_STATE: "ACTIVE",
+} as const;
+
+export const PROJECT_PHASES = [
+    "PHASE_0",
+    "PHASE_1",
+    "PHASE_2",
+    "PHASE_3",
+    "PHASE_4",
+] as const;
+
+// ─── Adapter platform directories (native / legacy) ───────────────────────────
+
+export const ADAPTER_DIRS = {
+    GEMINI: ".gemini",
+    CLAUDE: ".claude",
+    GROK: ".grok",
+    CURSOR: ".cursor",
+    CODEX: ".agents",
+    ANTIGRAVITY: ".antigravity",
+    LOCAL: ".atabey",
+    LEGACY_AGENT: ".agent",
+} as const;
+
+/** Priority order for framework directory resolution (CLI + MCP). */
+export const FRAMEWORK_DIR_CANDIDATES = [
+    FRAMEWORK.CORE_DIR,
+    ADAPTER_DIRS.CODEX,
+    ADAPTER_DIRS.CLAUDE,
+    ADAPTER_DIRS.GEMINI,
+    ADAPTER_DIRS.GROK,
+    ADAPTER_DIRS.CURSOR,
+    ADAPTER_DIRS.ANTIGRAVITY,
+    ADAPTER_DIRS.LOCAL,
+] as const;
+
+/** Slug under `.agents/{slug}/` for each adapter in unified mode. */
+export const UNIFIED_ADAPTER_SLUG = {
+    gemini: "gemini",
+    claude: "claude",
+    grok: "grok",
+    cursor: "cursor",
+    codex: "codex",
+    local: "local",
+    "antigravity-cli": "antigravity",
+} as const;
+
+export type UnifiedAdapterSlug = keyof typeof UNIFIED_ADAPTER_SLUG;
+
+// ─── Native agent instruction paths (legacy tool compatibility) ───────────────
+
+export const NATIVE_AGENT_PATHS = {
+    gemini: pathJoin(ADAPTER_DIRS.GEMINI, "agents"),
+    claude: pathJoin(ADAPTER_DIRS.CLAUDE, "agents"),
+    grok: pathJoin(ADAPTER_DIRS.GROK, "agents"),
+    cursor: pathJoin(ADAPTER_DIRS.CURSOR, "rules"),
+    codex: pathJoin(ADAPTER_DIRS.CODEX, "instructions"),
+    local: pathJoin(ADAPTER_DIRS.LOCAL, "agents"),
+    "antigravity-cli": pathJoin(ADAPTER_DIRS.ANTIGRAVITY, "agents"),
+} as const;
+
+/** Legacy layout bases used by `check` and discovery (non-unified installs). */
+export const LEGACY_AGENT_LAYOUT_BASES = [
+    NATIVE_AGENT_PATHS.gemini,
+    NATIVE_AGENT_PATHS.claude,
+    NATIVE_AGENT_PATHS.cursor,
+    NATIVE_AGENT_PATHS.grok,
+    NATIVE_AGENT_PATHS.codex,
+    NATIVE_AGENT_PATHS.local,
+    NATIVE_AGENT_PATHS["antigravity-cli"],
+] as const;
+
+// ─── Framework internal subdirectories (under `.atabey/`) ──────────────────
+
+export const FRAMEWORK_SUBDIRS = {
+    AGENTS: "agents",
+    SKILLS: "skills",
+    KNOWLEDGE: "knowledge",
+    PROMPTS: "prompts",
+    MEMORY: "memory",
+    ROUTER: "router",
+    REGISTRY: "registry",
+    OBSERVABILITY: "observability",
+    RULES: "rules",
+    MESSAGES: "messages",
+    LOGS: "logs",
+    MEMORY_GRAPH: "memory-graph",
+} as const;
+
+export const CORE_SCAFFOLD_SUBDIRS = [
+    FRAMEWORK_SUBDIRS.KNOWLEDGE,
+    FRAMEWORK_SUBDIRS.PROMPTS,
+    FRAMEWORK_SUBDIRS.MEMORY,
+    FRAMEWORK_SUBDIRS.ROUTER,
+    FRAMEWORK_SUBDIRS.REGISTRY,
+    FRAMEWORK_SUBDIRS.OBSERVABILITY,
+    FRAMEWORK_SUBDIRS.RULES,
+] as const;
+
+export const RUNTIME_SUBDIRS = [
+    FRAMEWORK_SUBDIRS.MESSAGES,
+    FRAMEWORK_SUBDIRS.LOGS,
+    FRAMEWORK_SUBDIRS.MEMORY_GRAPH,
+] as const;
+
+export const MEMORY_SUBDIRS = {
+    TASKS: "tasks",
+    HISTORY: "history",
+} as const;
+
+export const MEMORY_FILES = {
+    STATE: "state.json",
+    STATUS: "status.json",
+    PROJECT_MEMORY: "PROJECT_MEMORY.md",
+    SHARED_FACTS: "shared-facts.json",
+} as const;
+
+// ─── Monorepo default paths ───────────────────────────────────────────────────
+
+export const DEFAULT_MONOREPO_PATHS = {
+    backend: "apps/backend",
+    frontend: "apps/web",
+    mobile: "apps/mobile",
+    docs: "docs",
+    tests: "tests",
+} as const;
+
+/** Cursor rule globs per agent role (enterprise monorepo layout). */
+export const CURSOR_AGENT_GLOBS: Record<string, string> = {
+    manager:   "**/*",
+    security:  "**/*",
+    architect: "**/*",
+    backend:   `${DEFAULT_MONOREPO_PATHS.backend}/**/*`,
+    frontend:  `${DEFAULT_MONOREPO_PATHS.frontend}/**/*`,
+    mobile:    `${DEFAULT_MONOREPO_PATHS.mobile}/**/*`,
+    native:    "apps/native/**/*",
+    database:  `${DEFAULT_MONOREPO_PATHS.backend}/src/database/**/*`,
+    devops:    "{.github,docker,infra,scripts,*.yml,*.yaml,Dockerfile*}",
+    quality:   "**/*",
+    analyst:   "{docs,specs,contracts}/**/*",
+    explorer:  "**/*",
+    git:       "**/*",
+};
+
+// ─── MCP & environment ──────────────────────────────────────────────────────
+
+export const MCP = {
+    SERVER_NAME: "atabey",
+    ROOT_CONFIG_FILE: "mcp.json",
+    PROJECT_ROOT_ENV: "ATABEY_PROJECT_ROOT",
+    TEST_DIR_ENV: "ATABEY_TEST_DIR",
+} as const;
+
+export const ROOT_CONFIG_FILES = {
+    MCP: MCP.ROOT_CONFIG_FILE,
+    DOT_MCP: ".mcp.json",
+    ENV_EXAMPLE: ".env.example",
+    VSCODE_MCP: ".vscode/mcp.json",
+} as const;
+
+// ─── Shim template placeholders ───────────────────────────────────────────────
+
+export const TEMPLATE_PLACEHOLDERS = {
+    FRAMEWORK_DIR: "{{FRAMEWORK_DIR}}",
+    ADAPTER: "{{ADAPTER}}",
+    BACKEND_DIR: "{{BACKEND_DIR}}",
+    FRONTEND_DIR: "{{FRONTEND_DIR}}",
+    DOCS_DIR: "{{DOCS_DIR}}",
+    TESTS_DIR: "{{TESTS_DIR}}",
+} as const;
+
+// ─── File extensions ─────────────────────────────────────────────────────────
+
+export const AGENT_FILE_EXT = {
+    MARKDOWN: ".md",
+    CURSOR_RULE: ".mdc",
+} as const;
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+export function pathJoin(...segments: string[]): string {
+    return segments.filter(Boolean).join("/");
+}
+
+export function corePath(...segments: string[]): string {
+    return pathJoin(FRAMEWORK.CORE_DIR, ...segments);
+}
+
+export function unifiedHubPath(...segments: string[]): string {
+    return pathJoin(FRAMEWORK.UNIFIED_HUB_DIR, ...segments);
+}
+
+export function unifiedAdapterPath(slug: string, ...segments: string[]): string {
+    return unifiedHubPath(slug, ...segments);
+}
+
+export function knowledgePath(filename: string): string {
+    return corePath(FRAMEWORK_SUBDIRS.KNOWLEDGE, filename);
+}
+
+/** Backward-compatible aliases */
+export const CORE_FRAMEWORK_DIR = FRAMEWORK.CORE_DIR;
+export const UNIFIED_HUB_DIR = FRAMEWORK.UNIFIED_HUB_DIR;
+export const SKILLS_HUB_PATH = pathJoin(UNIFIED_HUB_DIR, FRAMEWORK_SUBDIRS.SKILLS);

package/src/shared/errors.ts

@@ -0,0 +1,75 @@
+/**
+ * Enterprise Base Error class for the Agent Atabey Framework.
+ */
+export class AtabeyBaseError extends Error {
+    public readonly code: string;
+    public readonly timestamp: Date;
+    public readonly details?: unknown;
+    public readonly solution?: string;
+
+    constructor(message: string, code = "ATABEY_INTERNAL_ERROR", details?: unknown, solution?: string) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.timestamp = new Date();
+        this.details = details;
+        this.solution = solution;
+        
+        // Ensure proper prototype chain and capture stack trace
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+
+    /**
+     * Converts the error into a structured JSON log format.
+     */
+    public toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            details: this.details,
+            solution: this.solution,
+            stack: this.stack,
+        };
+    }
+}
+
+/**
+ * Thrown when configuration loading or validation fails.
+ */
+export class ConfigurationError extends AtabeyBaseError {
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "CONFIGURATION_ERROR", details, solution);
+    }
+}
+
+/**
+ * Thrown when data schema or payload validation fails.
+ */
+export class ValidationError extends AtabeyBaseError {
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "VALIDATION_ERROR", details, solution);
+    }
+}
+
+/**
+ * Thrown when adapter initialization or execution fails.
+ */
+export class AdapterError extends AtabeyBaseError {
+    constructor(message: string, adapterId: string, details?: unknown, solution?: string) {
+        super(`Adapter '${adapterId}' failure: ${message}`, "ADAPTER_ERROR", details, solution);
+    }
+}
+
+/**
+ * Thrown when orchestration or agent communication fails.
+ */
+export class OrchestrationError extends AtabeyBaseError {
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "ORCHESTRATION_ERROR", details, solution);
+    }
+}

package/src/shared/fs.ts

@@ -0,0 +1,50 @@
+import fs from "fs";
+import path from "path";
+import { logger } from "./logger.js";
+
+export function ensureDir(dirPath: string, dryRun = false): void {
+    if (!fs.existsSync(dirPath)) {
+        if (dryRun) {
+            logger.info(`[DRY RUN] Would create directory: ${dirPath}`);
+        } else {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    }
+}
+
+/**
+ * Writes content to a file atomically by using a temporary file.
+ * This prevents data corruption during unexpected system failures.
+ */
+export function writeTextFile(filePath: string, content: string, dryRun = false): void {
+    if (dryRun) {
+        logger.info(`[DRY RUN] Would write file: ${filePath}`);
+        return;
+    }
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    } catch (err) {
+        if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+        throw err;
+    }
+}
+
+export function appendFile(filePath: string, content: string, dryRun = false): void {
+    if (dryRun) {
+        logger.info(`[DRY RUN] Would append to file: ${filePath}`);
+        return;
+    }
+    ensureDir(path.dirname(filePath));
+    fs.appendFileSync(filePath, content, "utf8");
+}
+
+export function writeJsonFile(filePath: string, value: unknown, dryRun = false): void {
+    writeTextFile(filePath, JSON.stringify(value, null, 2), dryRun);
+}

package/src/shared/logger.ts

@@ -0,0 +1,139 @@
+import chalk from "chalk";
+import path from "path";
+import { ensureDir, appendFile } from "./fs.js";
+
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4,
+}
+
+export interface LoggerConfig {
+    minLevel: LogLevel;
+    enableColors: boolean;
+    jsonFormat: boolean;
+    logFile?: string;
+}
+
+export class EnterpriseLogger {
+    private config: LoggerConfig;
+    private static instance: EnterpriseLogger;
+
+    private constructor() {
+        const isProd = process.env.NODE_ENV === "production";
+        this.config = {
+            minLevel: isProd ? LogLevel.INFO : LogLevel.DEBUG,
+            enableColors: !isProd,
+            jsonFormat: isProd,
+        };
+    }
+
+    public static getInstance(): EnterpriseLogger {
+        if (!EnterpriseLogger.instance) {
+            EnterpriseLogger.instance = new EnterpriseLogger();
+        }
+        return EnterpriseLogger.instance;
+    }
+
+    public configure(config: Partial<LoggerConfig>): void {
+        this.config = { ...this.config, ...config };
+        
+        if (this.config.logFile) {
+            try {
+                ensureDir(path.dirname(this.config.logFile));
+            } catch (err) {
+                // Directly write to stderr — using console here would be circular
+                process.stderr.write(`[Logger] Failed to create log directory: ${err}\n`);
+            }
+        }
+    }
+
+    private formatMessage(level: LogLevel, message: string, meta?: unknown): string {
+        const timestamp = new Date().toISOString();
+        const pid = process.pid;
+
+        if (this.config.jsonFormat) {
+            return JSON.stringify({
+                timestamp,
+                level: LogLevel[level],
+                pid,
+                message,
+                meta,
+            });
+        }
+
+        const levelName = LogLevel[level].padEnd(5);
+        let coloredLevel = levelName;
+
+        if (this.config.enableColors) {
+            switch (level) {
+                case LogLevel.DEBUG:
+                    coloredLevel = chalk.blue(levelName);
+                    break;
+                case LogLevel.INFO:
+                    coloredLevel = chalk.green(levelName);
+                    break;
+                case LogLevel.WARN:
+                    coloredLevel = chalk.yellow(levelName);
+                    break;
+                case LogLevel.ERROR:
+                    coloredLevel = chalk.red(levelName);
+                    break;
+                case LogLevel.FATAL:
+                    coloredLevel = chalk.bgRed.white.bold(levelName);
+                    break;
+            }
+        }
+
+        const metaStr = meta ? ` | Meta: ${JSON.stringify(meta)}` : "";
+        return `[${timestamp}] [PID:${pid}] [${coloredLevel}]: ${message}${metaStr}`;
+    }
+
+    private log(level: LogLevel, message: string, meta?: unknown): void {
+        if (level < this.config.minLevel) return;
+
+        const formatted = this.formatMessage(level, message, meta);
+
+        // Route to stderr for ERROR/FATAL, stdout otherwise.
+        // Using process.write directly here is intentional — this IS the logger.
+        if (level >= LogLevel.ERROR) {
+            process.stderr.write(formatted + "\n");
+        } else {
+            process.stdout.write(formatted + "\n");
+        }
+
+        // Output to file if configured
+        if (this.config.logFile) {
+            try {
+                appendFile(this.config.logFile, formatted + "\n");
+            } catch (err) {
+                // Directly write to stderr — using console here would be circular
+                process.stderr.write(`[Logger] Failed to write to log file: ${err}\n`);
+            }
+        }
+    }
+
+    public debug(message: string, meta?: unknown): void {
+        this.log(LogLevel.DEBUG, message, meta);
+    }
+
+    public info(message: string, meta?: unknown): void {
+        this.log(LogLevel.INFO, message, meta);
+    }
+
+    public warn(message: string, meta?: unknown): void {
+        this.log(LogLevel.WARN, message, meta);
+    }
+
+    public error(message: string, meta?: unknown): void {
+        this.log(LogLevel.ERROR, message, meta);
+    }
+
+    public fatal(message: string, meta?: unknown): void {
+        this.log(LogLevel.FATAL, message, meta);
+    }
+}
+
+export const logger = EnterpriseLogger.getInstance();

package/src/shared/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent Atabey Framework — Internal Branded Types
+ * Used to enforce absolute type safety within the core orchestration logic.
+ */
+
+export type Brand<K, T> = K & { __brand: T };
+
+export type TraceID = Brand<string, "TraceID">;
+export type AgentID = Brand<string, "AgentID">;
+export type PhaseID = Brand<string, "PhaseID">;
+export type ProjectPath = Brand<string, "ProjectPath">;
+
+/**
+ * Casts a raw string to a Branded Type.
+ * Use this only at the boundaries of the system.
+ */
+export function asTraceID(val: string): TraceID { return val as TraceID; }
+export function asAgentID(val: string): AgentID { return val as AgentID; }
+export function asPhaseID(val: string): PhaseID { return val as PhaseID; }
+export function asProjectPath(val: string): ProjectPath { return val as ProjectPath; }

package/templates/prompts/bug-fix-recipe.md

@@ -0,0 +1,20 @@
+# 🐞 Scientific Debugging (Bug-Fix) Recipe
+
+This recipe defines how to autonomously detect and permanently resolve a bug.
+
+## 1. Reproduction
+- Analyze the logs (`audit_log.md`) that reported the error.
+- Write the smallest test case (failing test) that triggers the error.
+
+## 2. Root Cause Analysis
+- Check system resources with `get_system_health`.
+- Verify the status of services with `check_active_ports`.
+- Examine relevant code blocks line by line using `read_file`.
+
+## 3. Surgical Fix
+- Perform only the surgical intervention that will fix the error.
+- Check if there is a missing variable in ".env".
+
+## 4. Permanent Solution
+- Verify that the test you wrote passes.
+- If `quality-standards.md` needs to be updated to prevent similar errors, submit a proposal.

package/templates/prompts/contract-design-recipe.md

@@ -0,0 +1,21 @@
+# 📜 Engineering Recipe: Contract-First Design
+
+This recipe governs the @architect agent's protocol for creating type-safe agreements between system layers.
+
+## 🏁 Phase 1: Requirement Alignment
+1.  **Analysis:** Read user requirements and Business Analyst (@analyst) reports.
+2.  **Scope Discovery:** Identify the domain objects, actions, and events required for the feature.
+
+## 📐 Phase 2: Technical Modeling
+1.  **Branded Types:** Define semantic IDs in `src/types/brands.ts` (e.g., `OrderId`, `ProductSKU`).
+2.  **Domain Models:** Create or update interfaces in `src/types/models.ts`. Ensure they extend `BaseEntity`.
+3.  **Constants:** Update `src/types/constants.ts` for enums and fixed state values.
+
+## 🔏 Phase 3: Hash Sealing
+1.  **Integrity Check:** Run `atabey verify-contract` to check existing state.
+2.  **Commitment:** Run `atabey update-contract` to generate new SHA-256 signatures for the updated types.
+3.  **Audit:** Verify that `contract.version.json` accurately reflects the new architecture.
+
+## 📡 Phase 4: Synchronization
+1.  **Distribution:** Ensure the updated `src/types` directory is correctly linked or copied to both Frontend and Backend projects.
+2.  **Verification:** Trigger @backend and @frontend agents to read the new contract and plan their implementations.

package/templates/prompts/db-management-recipe.md

@@ -0,0 +1,25 @@
+# 🗄️ Engineering Recipe: Database Management & Migrations
+
+This recipe governs the @database agent's protocol for schema creation, table modifications, and data integrity.
+
+## 📐 Phase 1: Contract-First Definition
+1.  **Type Mapping:** Define the new table or column in `src/types/models.ts` using Branded Types for IDs.
+2.  **Validation:** Ensure the interface extends `BaseEntity` (id, createdAt, updatedAt).
+
+## 🚀 Phase 2: Migration Generation
+1.  **Scripting:** Write a reversible migration (up/down) using the project's migration tool (e.g., Kysely or SQL).
+2.  **Atomic Changes:** One migration per logical feature. Never bundle unrelated schema changes.
+3.  **Naming:** Use timestamp-prefixed naming (e.g., `20240101_add_customers_table.ts`).
+
+## 🧱 Phase 3: Infrastructure Setup (If New DB)
+1.  **Initialization:** Verify the connection string in `.env`.
+2.  **Health Check:** Run `check_active_ports` to ensure the DB engine is reachable.
+
+## 🛠️ Phase 4: Implementation & Repository Update
+1.  **Repo Layer:** Create or update the Repository class to include the new query logic.
+2.  **Strict Mode:** Ensure no raw SQL is used; leverage the query builder exclusively.
+
+## ✅ Phase 5: Verification & Zero-Downtime Audit
+1.  **Dry Run:** If supported, dry-run the migration to check for locking issues.
+2.  **Validation:** Run `atabey verify-contract` to ensure code and schema are synced.
+3.  **Handoff:** Update `PROJECT_MEMORY.md` with the new schema version.

package/templates/prompts/deployment-recipe.md

@@ -0,0 +1,23 @@
+# 🚀 Engineering Recipe: Infrastructure Deployment
+
+This recipe governs the @devops agent's protocol for safe, traceable, and reversible system rollouts.
+
+## 🏁 Phase 1: Pre-Deployment Environment Audit
+1.  **Integrity Check:** Run `atabey check` to ensure all discipline rules are met.
+2.  **Health Scan:** Execute `get_system_health` and `check_active_ports` on the target environment.
+3.  **Config Sync:** Verify that all keys in `.env.example` are present in the target environment's secrets manager.
+
+## 🧱 Phase 2: Build & Validation
+1.  **Compilation:** Run `npm run build` and capture any stderr.
+2.  **Contract Verify:** Run `atabey verify-contract` to ensure FE/BE synchronization.
+3.  **Test Suite:** Execute the full test battery. Failure in a single test blocks deployment.
+
+## 📡 Phase 3: Controlled Rollout
+1.  **Atomic Swap:** Deploy the new bundle/service using the project's orchestration scripts.
+2.  **Database Sync:** If migrations are pending, follow the `db-management-recipe.md` first.
+3.  **Log Monitoring:** Tail `logs/manager.json` for immediate post-deploy spikes in errors.
+
+## ✅ Phase 4: Post-Deploy & Rollback Readiness
+1.  **Observability:** Verify system metrics stabilize within 5 minutes.
+2.  **Traceability:** Record the deployment Trace ID and commit hash in `PROJECT_MEMORY.md`.
+3.  **Rollback Check:** Ensure the previous stable version is tagged and reachable in Git.

package/templates/prompts/new-feature-recipe.md

@@ -0,0 +1,19 @@
+# ✨ New Feature Development Recipe
+
+The "Nizam-ı Atabey" steps to follow when adding a new module or feature.
+
+## 1. Contract Design (Phase 1)
+- First, update the `contract.version.json` file and the relevant TypeScript types.
+- Do not start writing code without getting approval from `@architect`.
+
+## 2. Mock-Free Development (Phase 2)
+- Add the new feature to the correct directory under `apps/backend` or `apps/web`.
+- If database changes are required, coordinate with the `@database` agent.
+
+## 3. Responsive & i18n (Phase 3)
+- Use `{ base: '...', md: '...' }` responsive syntax in frontend developments.
+- Move all texts to the `locales/` directory immediately.
+
+## 4. Completion (Phase 4)
+- Ensure no TODOs remain using `get_project_gaps`.
+- Verify that you haven't created any new package pollution with `audit_dependencies`.

package/templates/prompts/performance-optimization-recipe.md

@@ -0,0 +1,23 @@
+# ⚡ Engineering Recipe: Performance Optimization
+
+This recipe governs the protocol for identifying and resolving system bottlenecks (Frontend, Backend, or Database).
+
+## 📊 Phase 1: Profiling & Bottleneck Identification
+1.  **Metric Collection:** Read `observability/metrics.json` or run `get_system_health`.
+2.  **Log Audit:** Scan `logs/manager.json` for slow actions or timeouts.
+3.  **Trace Analysis:** Use `TraceID` to follow a slow request through all layers.
+
+## 🧠 Phase 2: Root Cause Analysis
+1.  **SQL Audit:** Check for N+1 query patterns or missing indexes in `repository/` files.
+2.  **Algorithm Audit:** Scan for O(n²) loops or heavy synchronous operations.
+3.  **Frontend Audit:** Check for unnecessary re-renders or massive bundle sizes.
+
+## 🛠️ Phase 3: Surgical Optimization
+1.  **DB Level:** Add missing indexes or refactor complex joins.
+2.  **Logic Level:** Implement caching (e.g., Redis or in-memory) for frequent read operations.
+3.  **UI Level:** Apply memoization, virtualization (FlashList), or code-splitting.
+
+## ✅ Phase 4: Validation & Comparison
+1.  **Benchmarking:** Re-run the action and compare new metrics with the baseline.
+2.  **Regression Check:** Run `atabey check` and existing tests to ensure logic is intact.
+3.  **Knowledge Update:** Record the optimization strategy in `knowledge/performance-history.md`.

package/templates/prompts/pull-request-template.md

@@ -0,0 +1,21 @@
+# 📦 Pull Request Title: [TRC-{TraceId}] Brief Description
+
+## 📝 Summary
+<!-- What did you change and why? -->
+
+## 🔗 Related Tasks
+- **Trace ID:** [Link to Trace/Task or ID]
+- **Issue:** [Link to issue if applicable]
+
+## 🛡️ Governance & Compliance Checklist
+- [ ] Code passes `npm run atabey:test`.
+- [ ] Code passes `npm run atabey:check` (Compliance Scanner).
+- [ ] No `any` type usage added.
+- [ ] No secrets or hardcoded API keys.
+- [ ] New functionality is registered in `src/modules/agents/definitions.ts` (if applicable).
+
+## 🧪 Testing Notes
+<!-- How did you verify the fix? -->
+
+## 🛠️ Risk Assessment
+<!-- Any potential side effects? -->