@pikaa-ai/pikaa 0.3.10 → 0.3.12

package/dist/cli.js

@@ -3,7 +3,7 @@
 
 // src/cli/index.ts
 import { resolve as resolve21 } from "path";
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 import { createInterface } from "readline";
 
 // src/auth/store.ts
@@ -6043,7 +6043,7 @@ function parsePatch(oldSrc, newSrc, contextLines = 3) {
 // package.json
 var package_default = {
   name: "@pikaa-ai/pikaa",
-  version: "0.3.10",
+  version: "0.3.12",
   description: "PIKAA CLI - AI coding agent that runs locally in your terminal.",
   main: "./dist/index.js",
   module: "./dist/index.js",
@@ -7766,9 +7766,441 @@ if (false) {}
 var __dirname = "/home/runner/work/agent-cli/agent-cli/src/mcp/servers/sqlite";
 var SQLITE_MCP_SERVER_PATH = resolve20(__dirname, "server.ts");
 
+// src/init/project-analyzer.ts
+import { existsSync as existsSync18, readFileSync as readFileSync13, readdirSync as readdirSync6 } from "fs";
+import { join as join9, basename as basename2 } from "path";
+
+class ProjectAnalyzer {
+  cwd;
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+  analyze() {
+    const readmeInfo = this.extractReadmeMetadata();
+    const projectName = readmeInfo.title || this.detectProjectName();
+    const languages = this.detectLanguages();
+    const packageManager = this.detectPackageManager();
+    const frameworks = [];
+    const infrastructure = [];
+    const commands = {};
+    const architectureNotes = [];
+    const codeConventions = [];
+    let description = readmeInfo.description;
+    const pkgPath = join9(this.cwd, "package.json");
+    if (existsSync18(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
+        if (!description && pkg.description)
+          description = pkg.description;
+        const pm = packageManager || "npm";
+        const runPrefix = pm === "bun" || pm === "yarn" || pm === "pnpm" ? `${pm} run` : "npm run";
+        const testPrefix = pm === "bun" ? "bun test" : pm === "pnpm" ? "pnpm test" : pm === "yarn" ? "yarn test" : "npm test";
+        if (pkg.scripts) {
+          if (pkg.scripts.dev)
+            commands.dev = `${runPrefix} dev`;
+          else if (pkg.scripts.start)
+            commands.dev = `${runPrefix} start`;
+          if (pkg.scripts.build)
+            commands.build = `${runPrefix} build`;
+          if (pkg.scripts.test)
+            commands.test = pkg.scripts.test === "bun test" ? "bun test" : testPrefix;
+          if (pkg.scripts.typecheck)
+            commands.typecheck = `${runPrefix} typecheck`;
+          else if (pkg.scripts.check)
+            commands.typecheck = `${runPrefix} check`;
+          if (pkg.scripts.lint)
+            commands.lint = `${runPrefix} lint`;
+          if (pkg.scripts.format)
+            commands.format = `${runPrefix} format`;
+        }
+        const allDeps = {
+          ...pkg.dependencies || {},
+          ...pkg.devDependencies || {}
+        };
+        if (allDeps.next)
+          frameworks.push("Next.js");
+        if (allDeps.react)
+          frameworks.push("React");
+        if (allDeps.vue)
+          frameworks.push("Vue.js");
+        if (allDeps.svelte || allDeps["@sveltejs/kit"])
+          frameworks.push("Svelte");
+        if (allDeps.astro)
+          frameworks.push("Astro");
+        if (allDeps.vite)
+          frameworks.push("Vite");
+        if (allDeps.express)
+          frameworks.push("Express");
+        if (allDeps.hono)
+          frameworks.push("Hono");
+        if (allDeps.fastify)
+          frameworks.push("Fastify");
+        if (allDeps["@nestjs/core"])
+          frameworks.push("NestJS");
+        if (allDeps.tailwindcss)
+          frameworks.push("TailwindCSS");
+        if (allDeps["lucide-react"] || allDeps.lucide)
+          frameworks.push("Lucide Icons");
+        if (allDeps.zustand)
+          frameworks.push("Zustand");
+        if (allDeps["@tanstack/react-query"])
+          frameworks.push("TanStack Query");
+        if (allDeps.oxlint)
+          frameworks.push("Oxlint");
+        if (allDeps.eslint)
+          frameworks.push("ESLint");
+        if (allDeps.vitest)
+          frameworks.push("Vitest");
+        if (allDeps.jest)
+          frameworks.push("Jest");
+        if (allDeps.playwright || allDeps["@playwright/test"])
+          frameworks.push("Playwright");
+        if (pkg.type === "module") {
+          codeConventions.push("Use ES modules (`import/export`), not CommonJS (`require`).");
+        }
+      } catch {}
+    }
+    const tsconfigPath = join9(this.cwd, "tsconfig.json");
+    if (existsSync18(tsconfigPath)) {
+      try {
+        const tsconfig = JSON.parse(readFileSync13(tsconfigPath, "utf8"));
+        if (tsconfig.compilerOptions?.strict) {
+          codeConventions.push("TypeScript strict mode enabled.");
+        }
+        if (!commands.typecheck) {
+          commands.typecheck = "tsc --noEmit";
+        }
+      } catch {}
+    }
+    const cargoPath = join9(this.cwd, "Cargo.toml");
+    if (existsSync18(cargoPath)) {
+      try {
+        commands.dev = commands.dev || "cargo run";
+        commands.build = commands.build || "cargo build";
+        commands.test = commands.test || "cargo test";
+        commands.lint = commands.lint || "cargo clippy";
+        frameworks.push("Rust Cargo");
+      } catch {}
+    }
+    const goModPath = join9(this.cwd, "go.mod");
+    if (existsSync18(goModPath)) {
+      try {
+        commands.dev = commands.dev || "go run .";
+        commands.build = commands.build || "go build ./...";
+        commands.test = commands.test || "go test ./...";
+        commands.lint = commands.lint || "golangci-lint run";
+        frameworks.push("Go Modules");
+      } catch {}
+    }
+    const pyprojectPath = join9(this.cwd, "pyproject.toml");
+    const requirementsPath = join9(this.cwd, "requirements.txt");
+    if (existsSync18(pyprojectPath) || existsSync18(requirementsPath)) {
+      commands.test = commands.test || "pytest";
+      commands.lint = commands.lint || "ruff check .";
+      if (existsSync18(join9(this.cwd, "uv.lock"))) {
+        frameworks.push("uv");
+        commands.test = "uv run pytest";
+      } else if (existsSync18(join9(this.cwd, "poetry.lock"))) {
+        frameworks.push("Poetry");
+        commands.test = "poetry run pytest";
+      }
+    }
+    if (existsSync18(join9(this.cwd, "Dockerfile"))) {
+      infrastructure.push("Docker");
+      const sanitizedName = projectName.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+      commands.dockerBuild = `docker build -t ${sanitizedName || "app"} .`;
+    }
+    if (existsSync18(join9(this.cwd, "nginx.conf"))) {
+      infrastructure.push("Nginx");
+    }
+    if (existsSync18(join9(this.cwd, "src/api.ts")) || existsSync18(join9(this.cwd, "src/api"))) {
+      architectureNotes.push("Backend API endpoints and network client logic are centralized in `src/api`.");
+    }
+    if (existsSync18(join9(this.cwd, "src/components"))) {
+      architectureNotes.push("Reusable UI presentation components live in `src/components/`.");
+    }
+    if (existsSync18(join9(this.cwd, "src/types.ts")) || existsSync18(join9(this.cwd, "src/types"))) {
+      architectureNotes.push("Shared TypeScript data models and interfaces are defined in `src/types`.");
+    }
+    if (existsSync18(join9(this.cwd, ".env.example"))) {
+      architectureNotes.push("Environment configuration template is in `.env.example`.");
+    }
+    if (commands.typecheck || commands.lint || commands.test) {
+      const checks = [];
+      if (commands.typecheck)
+        checks.push(`typecheck (\`${commands.typecheck}\`)`);
+      if (commands.lint)
+        checks.push(`lint (\`${commands.lint}\`)`);
+      if (commands.test)
+        checks.push(`tests (\`${commands.test}\`)`);
+      codeConventions.push(`Run ${checks.join(" and ")} before concluding any major code edits.`);
+    }
+    const instructionFiles = ["AGENTS.md", "CLAUDE.md", ".agents.md", "AGENTS.override.md"];
+    let hasExistingInstructions = false;
+    let existingInstructionFile;
+    for (const f of instructionFiles) {
+      if (existsSync18(join9(this.cwd, f))) {
+        hasExistingInstructions = true;
+        existingInstructionFile = f;
+        break;
+      }
+    }
+    return {
+      projectName,
+      description,
+      languages,
+      packageManager,
+      frameworks,
+      infrastructure,
+      commands,
+      architectureNotes,
+      codeConventions,
+      hasExistingInstructions,
+      existingInstructionFile
+    };
+  }
+  generateAgentsMarkdown(analysis) {
+    const lines = [];
+    lines.push(`# ${analysis.projectName}`);
+    lines.push("");
+    if (analysis.description) {
+      lines.push(`> ${analysis.description}`);
+      lines.push("");
+    }
+    lines.push("## Commands");
+    lines.push("");
+    if (Object.keys(analysis.commands).length > 0) {
+      if (analysis.commands.dev)
+        lines.push(`- **Dev Server**: \`${analysis.commands.dev}\``);
+      if (analysis.commands.build)
+        lines.push(`- **Build**: \`${analysis.commands.build}\``);
+      if (analysis.commands.test)
+        lines.push(`- **Test**: \`${analysis.commands.test}\``);
+      if (analysis.commands.typecheck)
+        lines.push(`- **Typecheck**: \`${analysis.commands.typecheck}\``);
+      if (analysis.commands.lint)
+        lines.push(`- **Lint**: \`${analysis.commands.lint}\``);
+      if (analysis.commands.format)
+        lines.push(`- **Format**: \`${analysis.commands.format}\``);
+      if (analysis.commands.dockerBuild)
+        lines.push(`- **Docker Build**: \`${analysis.commands.dockerBuild}\``);
+    } else {
+      lines.push("- *No standard build/test commands detected.*");
+    }
+    lines.push("");
+    lines.push("## Architecture & Stack");
+    lines.push("");
+    const stackItems = [];
+    if (analysis.languages.length > 0)
+      stackItems.push(analysis.languages.join(", "));
+    if (analysis.frameworks.length > 0)
+      stackItems.push(analysis.frameworks.join(", "));
+    if (analysis.infrastructure.length > 0)
+      stackItems.push(analysis.infrastructure.join(", "));
+    if (stackItems.length > 0) {
+      lines.push(`- **Core Stack**: ${stackItems.join(" \u2022 ")}`);
+    }
+    for (const note of analysis.architectureNotes) {
+      lines.push(`- ${note}`);
+    }
+    lines.push("");
+    lines.push("## Workflow & Code Guidelines");
+    lines.push("");
+    if (analysis.codeConventions.length > 0) {
+      for (const conv of analysis.codeConventions) {
+        lines.push(`- ${conv}`);
+      }
+    }
+    lines.push("- Prefer targeted edits over whole-file rewrites.");
+    lines.push("- When fixing errors, address the root cause rather than suppressing compiler warnings.");
+    lines.push("");
+    return lines.join(`
+`);
+  }
+  extractReadmeMetadata() {
+    const readmeFiles = ["README.md", "readme.md", "README.MD"];
+    for (const file of readmeFiles) {
+      const fullPath = join9(this.cwd, file);
+      if (existsSync18(fullPath)) {
+        try {
+          const content = readFileSync13(fullPath, "utf8");
+          const lines = content.split(`
+`);
+          let title;
+          let description;
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!title && trimmed.startsWith("# ")) {
+              title = trimmed.replace(/^#\s+/, "").trim();
+              continue;
+            }
+            if (title && !description && trimmed.length > 0 && !trimmed.startsWith("#") && !trimmed.startsWith("```") && !trimmed.startsWith("[")) {
+              description = trimmed;
+              break;
+            }
+          }
+          return { title, description };
+        } catch {}
+      }
+    }
+    return {};
+  }
+  detectProjectName() {
+    const pkgPath = join9(this.cwd, "package.json");
+    if (existsSync18(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
+        if (pkg.name && pkg.name !== "frontend" && pkg.name !== "backend" && pkg.name !== "app") {
+          return pkg.name.startsWith("@") ? pkg.name.split("/")[1] || pkg.name : pkg.name;
+        }
+      } catch {}
+    }
+    const cargoPath = join9(this.cwd, "Cargo.toml");
+    if (existsSync18(cargoPath)) {
+      try {
+        const match = readFileSync13(cargoPath, "utf8").match(/name\s*=\s*"([^"]+)"/);
+        if (match?.[1])
+          return match[1];
+      } catch {}
+    }
+    const goModPath = join9(this.cwd, "go.mod");
+    if (existsSync18(goModPath)) {
+      try {
+        const match = readFileSync13(goModPath, "utf8").match(/module\s+([^\s]+)/);
+        if (match?.[1])
+          return basename2(match[1]);
+      } catch {}
+    }
+    return basename2(this.cwd);
+  }
+  detectLanguages() {
+    const langs = new Set;
+    if (existsSync18(join9(this.cwd, "tsconfig.json")) || this.hasFileWithExtension(".ts", ".tsx")) {
+      langs.add("TypeScript");
+    }
+    if (existsSync18(join9(this.cwd, "package.json")) || this.hasFileWithExtension(".js", ".jsx", ".mjs")) {
+      langs.add("JavaScript");
+    }
+    if (existsSync18(join9(this.cwd, "Cargo.toml")) || this.hasFileWithExtension(".rs")) {
+      langs.add("Rust");
+    }
+    if (existsSync18(join9(this.cwd, "go.mod")) || this.hasFileWithExtension(".go")) {
+      langs.add("Go");
+    }
+    if (existsSync18(join9(this.cwd, "pyproject.toml")) || existsSync18(join9(this.cwd, "requirements.txt")) || this.hasFileWithExtension(".py")) {
+      langs.add("Python");
+    }
+    if (existsSync18(join9(this.cwd, "pom.xml")) || existsSync18(join9(this.cwd, "build.gradle")) || this.hasFileWithExtension(".java")) {
+      langs.add("Java");
+    }
+    if (existsSync18(join9(this.cwd, "CMakeLists.txt")) || this.hasFileWithExtension(".cpp", ".c", ".h", ".hpp")) {
+      langs.add("C/C++");
+    }
+    return Array.from(langs);
+  }
+  detectPackageManager() {
+    if (existsSync18(join9(this.cwd, "bun.lockb")) || existsSync18(join9(this.cwd, "bun.lock")))
+      return "bun";
+    if (existsSync18(join9(this.cwd, "pnpm-lock.yaml")))
+      return "pnpm";
+    if (existsSync18(join9(this.cwd, "yarn.lock")))
+      return "yarn";
+    if (existsSync18(join9(this.cwd, "package-lock.json")))
+      return "npm";
+    if (existsSync18(join9(this.cwd, "Cargo.lock")) || existsSync18(join9(this.cwd, "Cargo.toml")))
+      return "cargo";
+    if (existsSync18(join9(this.cwd, "uv.lock")))
+      return "uv";
+    if (existsSync18(join9(this.cwd, "poetry.lock")))
+      return "poetry";
+    if (existsSync18(join9(this.cwd, "go.sum")) || existsSync18(join9(this.cwd, "go.mod")))
+      return "go";
+    if (existsSync18(join9(this.cwd, "package.json")))
+      return "npm";
+    return;
+  }
+  hasFileWithExtension(...exts) {
+    try {
+      const entries = readdirSync6(this.cwd);
+      return entries.some((e) => exts.some((ext) => e.endsWith(ext)));
+    } catch {
+      return false;
+    }
+  }
+}
+// src/init/init-command.ts
+import { existsSync as existsSync19, writeFileSync as writeFileSync7 } from "fs";
+import { join as join10 } from "path";
+function runProjectInit(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const filename = options.filename || "AGENTS.md";
+  const targetPath = join10(cwd, filename);
+  const analyzer = new ProjectAnalyzer(cwd);
+  const analysis = analyzer.analyze();
+  const content = analyzer.generateAgentsMarkdown(analysis);
+  const alreadyExists = existsSync19(targetPath);
+  writeFileSync7(targetPath, content, "utf8");
+  return {
+    success: true,
+    filePath: targetPath,
+    analysis,
+    content,
+    overwritten: alreadyExists
+  };
+}
+function printInitSummary(result) {
+  const BOLD2 = "\x1B[1m";
+  const GREEN = "\x1B[38;2;120;220;140m";
+  const BRAND = "\x1B[38;2;217;119;87m";
+  const CYAN = "\x1B[38;2;125;207;255m";
+  const GRAY2 = "\x1B[38;2;148;148;148m";
+  const WHITE2 = "\x1B[38;2;240;240;245m";
+  const RESET2 = "\x1B[0m";
+  const { analysis, filePath, overwritten } = result;
+  console.log("");
+  console.log(`  ${GREEN}\u2713${RESET2} ${BOLD2}${WHITE2}${overwritten ? "Updated" : "Created"} Project Instructions Document${RESET2}`);
+  console.log(`  ${GRAY2}Path: ${CYAN}${filePath}${RESET2}`);
+  console.log("");
+  console.log(`  ${BRAND}\u250C\u2500 ${BOLD2}Project Overview${RESET2} ${BRAND}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510${RESET2}`);
+  console.log(`  ${BRAND}\u2502${RESET2}  ${BOLD2}Project:${RESET2} ${WHITE2}${analysis.projectName}${RESET2}`);
+  if (analysis.languages.length > 0) {
+    console.log(`  ${BRAND}\u2502${RESET2}  ${BOLD2}Languages:${RESET2} ${analysis.languages.join(", ")}`);
+  }
+  if (analysis.packageManager) {
+    console.log(`  ${BRAND}\u2502${RESET2}  ${BOLD2}Package Manager:${RESET2} ${analysis.packageManager}`);
+  }
+  if (analysis.frameworks.length > 0) {
+    console.log(`  ${BRAND}\u2502${RESET2}  ${BOLD2}Frameworks:${RESET2} ${analysis.frameworks.join(", ")}`);
+  }
+  console.log(`  ${BRAND}\u2502${RESET2}`);
+  console.log(`  ${BRAND}\u2502${RESET2}  ${BOLD2}Detected Commands:${RESET2}`);
+  if (analysis.commands.build) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 Build:     ${CYAN}${analysis.commands.build}${RESET2}`);
+  }
+  if (analysis.commands.test) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 Test:      ${GREEN}${analysis.commands.test}${RESET2}`);
+  }
+  if (analysis.commands.typecheck) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 Typecheck: ${CYAN}${analysis.commands.typecheck}${RESET2}`);
+  }
+  if (analysis.commands.lint) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 Lint:      ${CYAN}${analysis.commands.lint}${RESET2}`);
+  }
+  if (analysis.commands.dev) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 Dev:       ${CYAN}${analysis.commands.dev}${RESET2}`);
+  }
+  if (Object.keys(analysis.commands).length === 0) {
+    console.log(`  ${BRAND}\u2502${RESET2}    \u2022 ${GRAY2}(No standard commands detected)${RESET2}`);
+  }
+  console.log(`  ${BRAND}\u2502${RESET2}`);
+  console.log(`  ${BRAND}\u2502${RESET2}  ${GRAY2}AI agents will now automatically load AGENTS.md on every session.${RESET2}`);
+  console.log(`  ${BRAND}\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518${RESET2}`);
+  console.log("");
+}
 // src/cli/commands.ts
 var AVAILABLE_SLASH_COMMANDS = [
   { name: "/help", description: "Show command list and help menu" },
+  { name: "/init", description: "Initialize or update AGENTS.md project instructions" },
   { name: "/stats", description: "Display session runtime, turn stats & sub-agent status" },
   { name: "/model", description: "Select or switch active AI model" },
   { name: "/reasoning", description: "Toggle internal reasoning chain visibility" },
@@ -7861,6 +8293,10 @@ async function handleSlashCommand(input, ctx) {
   \x1B[38;2;95;175;175m\u23F8 Switched to Plan Mode (read-only planning, mutations blocked)\x1B[0m
 `);
       return true;
+    case "/init":
+      const initResult = runProjectInit({ cwd: ctx.session.cwd });
+      printInitSummary(initResult);
+      return true;
     case "/agents":
       printAgents(ctx);
       return true;
@@ -9126,9 +9562,9 @@ class MarkdownHighlighter {
 }
 
 // src/cli/update-checker.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync10, readFileSync as readFileSync13, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync10, readFileSync as readFileSync14, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join9 } from "path";
+import { join as join11 } from "path";
 var CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 function parseSemver(v) {
   const clean = v.replace(/^v/, "").trim();
@@ -9149,8 +9585,8 @@ function isNewerVersion(current, remote) {
   return remPatch > curPatch;
 }
 function getUpdateCachePath() {
-  const baseDir = process.env.PIKAA_HOME || process.env.GROUPY_HOME || join9(homedir9(), ".pikaa");
-  return join9(baseDir, "update-cache.json");
+  const baseDir = process.env.PIKAA_HOME || process.env.GROUPY_HOME || join11(homedir9(), ".pikaa");
+  return join11(baseDir, "update-cache.json");
 }
 async function fetchLatestNpmVersion(packageName, timeoutMs = 1500) {
   const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
@@ -9183,9 +9619,9 @@ async function checkForUpdates(options = {}) {
   const cachePath = options.cachePath || getUpdateCachePath();
   const now = Date.now();
   let cached = null;
-  if (!options.force && existsSync18(cachePath)) {
+  if (!options.force && existsSync20(cachePath)) {
     try {
-      const raw = JSON.parse(readFileSync13(cachePath, "utf8"));
+      const raw = JSON.parse(readFileSync14(cachePath, "utf8"));
       if (raw && typeof raw.lastChecked === "number" && typeof raw.latestVersion === "string") {
         cached = raw;
         if (now - cached.lastChecked < CHECK_INTERVAL_MS) {
@@ -9213,8 +9649,8 @@ async function checkForUpdates(options = {}) {
     return null;
   }
   try {
-    const parentDir = join9(cachePath, "..");
-    if (!existsSync18(parentDir)) {
+    const parentDir = join11(cachePath, "..");
+    if (!existsSync20(parentDir)) {
       mkdirSync10(parentDir, { recursive: true });
     }
     const cacheData = {
@@ -9222,7 +9658,7 @@ async function checkForUpdates(options = {}) {
       latestVersion,
       packageName
     };
-    writeFileSync7(cachePath, JSON.stringify(cacheData, null, 2), "utf8");
+    writeFileSync8(cachePath, JSON.stringify(cacheData, null, 2), "utf8");
   } catch {}
   const updateAvailable = isNewerVersion(currentVersion, latestVersion);
   return updateAvailable ? {
@@ -9589,6 +10025,10 @@ async function main() {
     } else if (arg === "worktrees" || arg === "worktree") {
       await printWorktreesList(worktreeManager, cwd);
       process.exit(0);
+    } else if (arg === "init") {
+      const initResult = runProjectInit({ cwd });
+      printInitSummary(initResult);
+      process.exit(0);
     } else if (arg === "--resume" || arg === "-R" || arg === "resume") {
       resumeThreadId = args[++i];
     } else if (arg === "--model" || arg === "-m") {
@@ -9630,7 +10070,7 @@ async function main() {
     resolve21(cwd, "mcp_config.json")
   ].filter(Boolean);
   for (const cfg of candidateConfigs) {
-    if (existsSync19(cfg)) {
+    if (existsSync21(cfg)) {
       try {
         await mcpManager.loadConfigFile(cfg);
         mcpManager.registerToolsIntoRouter(tools4);
@@ -9888,6 +10328,7 @@ ${style.bold("USAGE:")}
   groupy skills                   # List available domain skills
   groupy memories                 # View learned user preferences
   groupy worktrees                # List active isolated Git Worktrees
+  groupy init                     # Initialize or update AGENTS.md project instructions
 
 ${style.bold("OPTIONS:")}
   -R, --resume <id>        Resume an existing session from SQLite storage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikaa-ai/pikaa",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "PIKAA CLI - AI coding agent that runs locally in your terminal.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/templates/base/groupy_prompt.md

@@ -47,6 +47,10 @@ You are Groupy, an expert autonomous AI coding assistant. You are running as a c
 
 ## Codebase Discovery & Execution Strategy
 
+0. **Project Instructions Precedence (`AGENTS.md` / `CLAUDE.md`)**:
+   - If `AGENTS.md`, `CLAUDE.md`, or `.agents.md` is present in the workspace, its instructions take immediate precedence.
+   - Always prioritize and follow the development commands (build, test, lint), architectural constraints, and code conventions defined in `AGENTS.md` before executing any commands.
+
 1. **Broad Exploration ("pelajari project ini / repo ini tentang apa")**:
    - Inspect ONLY root configs (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), `README.md`, and top-level directory tree.
    - Deliver a concise Architecture Overview (Tech stack, folder hierarchy, main entry points).