@nghyane/arcane 0.1.13 → 0.1.15

package/src/prompts/tools/reviewer.md

@@ -1,41 +0,0 @@
-# Review
-
-Review code changes using a specialized code review subagent. The reviewer identifies bugs the author would want fixed before merge — not style issues, not pre-existing bugs.
-
-## When to use
-- Review uncommitted changes, a specific commit, or a PR diff
-- Check code quality and correctness of recent modifications
-- Analyze a diff for bugs, security issues, or logic errors
-
-## When NOT to use
-- Simple file reading or code understanding (use Read/Grep/Explore)
-- Making code changes (use Edit/Write/Task)
-
-## Parameters
-
-### `diff_description` (required)
-
-A description or command that identifies the diff to review. Examples:
-- `"uncommitted changes"` — reviews `git diff`
-- `"last commit"` — reviews `git show HEAD`
-- `"PR #42"` — reviews `gh pr diff 42`
-- `"changes against main branch"` — reviews `git diff main...HEAD`
-
-### `files` (optional)
-
-Array of specific file paths to focus the review on. If omitted, all changed files are reviewed.
-
-### `instructions` (optional)
-
-Additional guidance for the reviewer. Examples:
-- `"Focus on error handling"`
-- `"Check for race conditions in the async code"`
-- `"Verify backward compatibility"`
-
-## Output
-
-Returns structured review with:
-- `overall_correctness`: "correct" or "incorrect"
-- `explanation`: 1-3 sentence verdict summary
-- `confidence`: 0.0-1.0
-- `findings`: list of issues found, each with title, body, priority (P0-P3), file path, and line range

package/src/prompts/tools/ssh.md

@@ -1,51 +0,0 @@
-# SSH
-
-Run commands on remote hosts.
-
-<instruction>
-Build commands from reference below
-</instruction>
-
-<commands>
-**linux/bash, linux/zsh, macos/bash, macos/zsh** — Unix-like:
-- Files: `ls`, `cat`, `head`, `tail`, `grep`, `find`
-- System: `ps`, `top`, `df`, `uname` (all), `free` (Linux only)
-- Navigation: `cd`, `pwd`
-**windows/bash, windows/sh** — Windows Unix layer (WSL, Cygwin, Git Bash):
-- Files/System/Navigation: same as Unix-like above, minus `free`
-**windows/powershell** — PowerShell:
-- Files: `Get-ChildItem`, `Get-Content`, `Select-String`
-- System: `Get-Process`, `Get-ComputerInfo`
-- Navigation: `Set-Location`, `Get-Location`
-**windows/cmd** — Command Prompt:
-- Files: `dir`, `type`, `findstr`, `where`
-- System: `tasklist`, `systeminfo`
-- Navigation: `cd`, `echo %CD%`
-</commands>
-
-<output>
-stdout/stderr combined, truncated at 50KB; exit code captured.
-If truncated, full output stored under $ARTIFACTS as `artifact://<id>`.
-</output>
-
-<critical>
-Verify shell type from "Available hosts", use matching commands.
-</critical>
-
-<example name="linux">
-Task: List /home/user files on "server1"
-Host: server1 (10.0.0.1) | linux/bash
-Command: `ls -la /home/user`
-</example>
-
-<example name="windows-cmd">
-Task: Show running processes on "winbox"
-Host: winbox (192.168.1.5) | windows/cmd
-Command: `tasklist /v`
-</example>
-
-<example name="macos">
-Task: Get system info on "macbook"
-Host: macbook (10.0.0.20) | macos/zsh
-Command: `uname -a && sw_vers`
-</example>

package/src/prompts/tools/task-summary.md

@@ -1,28 +0,0 @@
-<task-summary>
-<header>{{successCount}}/{{totalCount}} succeeded{{#if hasCancelledNote}} ({{cancelledCount}} cancelled){{/if}} [{{duration}}]</header>
-
-{{#each summaries}}
-<agent id="{{id}}" agent="{{agent}}">
-<status>{{status}}</status>
-{{#if meta}}<meta lines="{{meta.lineCount}}" size="{{meta.charSize}}" />{{/if}}
-{{#if truncated}}
-<preview full-path="agent://{{id}}">
-{{preview}}
-</preview>
-{{else}}
-<result>
-{{preview}}
-</result>
-{{/if}}
-</agent>
-{{#unless @last}}
----
-{{/unless}}
-{{/each}}
-
-{{#if patchApplySummary}}
-<patch-summary>
-{{patchApplySummary}}
-</patch-summary>
-{{/if}}
-</task-summary>

package/src/prompts/tools/task.md

@@ -1,146 +0,0 @@
-# Task
-
-Launch a fire-and-forget subagent to execute well-scoped work. Think of it as a productive junior engineer who cannot ask follow-ups once started.
-- **Use for**: Multi-file implementations, cross-layer refactors, mass migrations, boilerplate generation
-- **Don't use for**: Exploratory work, architectural decisions, single-file edits, reading a file
-
-## Subagent capabilities
-
-Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. They have no access to your conversation history — they don't know decisions you made, approaches you chose, or requirements stated only in conversation. Subagents CAN grep the parent conversation file for supplementary details.
----
-
-## Parameters
-
-### `context` (optional — strongly recommended)
-
-Shared background prepended verbatim to every task `assignment`. Use only for session-specific information subagents lack.
-
-<critical>
-Do NOT include project rules, coding conventions, or style guidelines — subagents already have AGENTS.md. Restating any rule from AGENTS.md in `context` is a bug.
-</critical>
-**Before writing each line of context, ask:** "Would this sentence be true for ANY task in this repo, or only for THIS specific batch?" If it applies to any task → the subagent already has it → delete the line.
-
-Use template; omit non-applicable sections:
-
-````
-## Goal
-One sentence: what the batch accomplishes together.
-
-## Non-goals
-Explicitly exclude tempting scope — what tasks must not touch.
-
-## Constraints
-- Task-specific MUST / MUST NOT rules not already in AGENTS.md
-- Decisions made during this session that affect implementation
-
-## Reference Files
-- `path/to/file.ext` — pattern demo
-
-## API Contract (if tasks produce/consume shared interface)
-```language
-// Exact type definitions, function signatures
-```
-
-## Acceptance (global)
-- Definition of "done" for batch
-- For parallel tasks, build/test/lint verification happens AFTER all tasks complete — not inside tasks. Single tasks may self-verify.
-````
-**Belongs in `context`**: session decisions, reference paths, shared type definitions, API contracts, global acceptance — anything 2+ tasks need that isn't in AGENTS.md.
-**Does NOT belong**: project rules from AGENTS.md, per-task file lists, one-off requirements (go in `assignment`).
-
-### `tasks` (required)
-
-Array of tasks that execute in parallel.
-
-|Field|Required|Purpose|
-|---|---|---|
-|`id`|yes|CamelCase identifier, max 32 chars|
-|`description`|yes|Short one-liner for UI display only — not seen by subagent|
-|`assignment`|yes|Complete per-task instructions (see below)|
-|`skills`||Skill names to preload. Use only when it changes correctness.|
----
-
-## Writing an assignment
-
-<critical>
-`assignment` must contain enough info for the subagent to act **without asking a clarifying question**. One-liners guarantee failure.
-
-Use this structure:
-
-```
-## Target
-- Files: exact path(s)
-- Symbols/entrypoints: specific functions, types, exports
-- Non-goals: what task must NOT touch
-
-## Change
-- Step-by-step: add/remove/rename/restructure
-- Patterns/APIs to use; reference files if applicable
-
-## Edge Cases / Don't Break
-- Tricky case 1: ...
-- Existing behavior that must survive: ...
-
-## Acceptance (task-local)
-- Expected behavior or observable result
-- For parallel tasks: DO NOT include project-wide build/test/lint commands
-```
-
-`context` carries shared background. `assignment` carries only delta: file-specific instructions, local edge cases, per-task acceptance.
-
-### Delegate intent, not keystrokes
-
-Your role is tech lead: set direction, define boundaries, call out pitfalls — then get out of the way. Don't dictate line-by-line edits.
-**Be specific about:** constraints, naming, API contracts, "don't break" items, acceptance criteria.
-**Delegate:** code reading, approach selection, exact edit locations, implementation details.
-</critical>
-
-### Anti-patterns
-**Vague assignments** — subagent guesses wrong or stalls:
-- "Refactor this to be cleaner."
-- "Fix the bug in streaming."
-- "Update all constructors in `src/**/*.ts`."
-**Test/lint in parallel tasks** — edit wars:
-Parallel agents share working tree. If two agents run `bun check` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. **Never tell parallel tasks to run project-wide build/test/lint.** Each task edits, stops. Caller verifies after all complete. Single-task launches may include verification.
-**If you can't specify scope yet**, create a **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
----
-
-## Task scope
-
-Each task: small, well-defined — **at most 3-5 files**.
-**Signs task is too broad:** file paths use globs, assignment says "update all" / "migrate everything", scope covers entire package.
-**Fix:** enumerate files first (grep/glob), then fan out one task per file or small cluster.
----
-
-## Parallelization
-**Test:** Can task B produce correct output without seeing task A's result?
-- **Yes** → parallelize
-- **No** → sequential (A completes, then launch B with A's output in context)
-
-### Must be sequential
-
-|First|Then|Reason|
-|---|---|---|
-|Define types/interfaces|Implement consumers|Consumers need contract|
-|Create API exports|Write bindings/callers|Callers need signatures|
-|Core module|Dependent modules|Dependents import from core|
-
-### Safe to parallelize
-- Independent modules, no cross-imports
-- Tests for already-implemented code
-- Isolated file-scoped refactors
-
-### Multi-phase pattern
-**Phase 1 — Sequential**: define shared contracts (types, interfaces, schemas).
-**Phase 2 — Parallel**: fan out tasks consuming same known interface.
-**Phase 3 — Integration** (do yourself): wire modules, fix mismatches, verify builds.
----
-
-## Pre-flight checklist
-
-Before calling tool, verify:
-- [ ] `context` includes only session-specific info not already in AGENTS.md
-- [ ] Each assignment has Target, Change, Edge Cases, Acceptance sections
-- [ ] Assignments reference exact file paths (no globs)
-- [ ] Scope small, file paths explicit
-- [ ] Parallel tasks don't run project-wide build/test/lint — you do after all tasks complete (single tasks may self-verify)

package/src/prompts/tools/todo-write.md

@@ -1,65 +0,0 @@
-# Todo Write
-
-Create/manage structured task list for coding session.
-
-<conditions>
-Use proactively:
-1. Complex multi-step tasks requiring 3+ steps/actions
-2. User requests todo list
-3. User provides multiple tasks (numbered/comma-separated)
-4. After new instructions—capture requirements as todos
-5. Starting task—mark in_progress BEFORE beginning
-6. After completing—mark completed, add follow-up tasks found
-</conditions>
-
-<protocol>
-1. **Task States**:
-	 - pending: not started
-	 - in_progress: working
-	 - completed: finished
-2. **Task Management**:
-   - Update status each turn
-   - Mark completed after each code execution finishes — do not defer to a later turn
-   - Multiple tasks may be in_progress simultaneously when working in parallel
-   - Remove tasks no longer relevant
-   - Mark tasks completed as they finish, regardless of list order
-3. **Task Completion Requirements**:
-   - ONLY mark completed when FULLY accomplished
-   - On errors/blockers/inability to finish, keep in_progress
-   - When blocked, create task describing what needs resolving
-4. **Task Breakdown**:
-	 - Create specific, actionable items
-	 - Keep each todo scoped to one logical unit of work; split unrelated work into separate items
-	 - Break complex tasks into smaller steps
-	 - Use clear, descriptive names
-</protocol>
-
-<output>
-Returns confirmation todo list updated.
-</output>
-
-<caution>
-When in doubt, use this.
-</caution>
-
-<example name="use-dark-mode">
-User: Add dark mode toggle to settings. Run tests when done.
-→ Creates todos: toggle component, state management, theme styles, update components, run tests
-</example>
-
-<example name="use-features">
-User: Implement user registration, product catalog, shopping cart, checkout.
-→ Creates todos per feature with subtasks
-</example>
-
-<example name="skip">
-User: Run npm install / Add a comment to this function / What does git status do?
-→ Do directly. Single-step/informational tasks need no tracking.
-</example>
-
-<avoid>
-Skip when:
-1. Single straightforward task
-2. Task completable in <3 trivial steps
-3. Task purely conversational/informational
-</avoid>

package/src/prompts/tools/undo-edit.md

@@ -1,7 +0,0 @@
-Undo the last edit made to a file, restoring it to the state before that edit.
-
-Only the most recent change per file can be undone. A second undo on the same file without an intervening edit will fail.
-
-Use when:
-- An edit introduced errors and re-editing would be more complex than starting over
-- A write overwrote content that needs to be restored

package/src/prompts/tools/web-search.md

@@ -1,19 +0,0 @@
-# Web Search
-
-Search the web for up-to-date information beyond Claude's knowledge cutoff.
-
-<instruction>
-- Prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
-- Include links for cited sources in the final response
-</instruction>
-
-<output>
-Returns search results formatted as blocks with:
-- Result summaries and relevant excerpts
-- Links as markdown hyperlinks for citation
-- Provider-dependent structure based on selected backend
-</output>
-
-<caution>
-Searches are performed automatically within a single API call—no pagination or follow-up requests needed.
-</caution>

package/src/prompts/tools/write.md

@@ -1,18 +0,0 @@
-# Write
-
-Creates or overwrites file at specified path.
-
-<conditions>
-- Creating new files explicitly required by task
-- Replacing entire file contents when editing would be more complex
-</conditions>
-
-<output>
-Confirmation of file creation/write with path. When LSP available, content may be auto-formatted before writing and diagnostics returned. Returns error if write fails (permissions, invalid path, disk full).
-</output>
-
-<critical>
-- Prefer Edit tool for modifying existing files (more precise, preserves formatting)
-- Create documentation files (*.md, README) only when explicitly requested
-- No emojis unless requested
-</critical>

package/src/task/batch.ts

@@ -1,102 +0,0 @@
-/**
- * Lightweight batch runner for subagent tasks.
- *
- * Encapsulates: agent resolution, artifacts dir lifecycle, concurrency execution, temp cleanup.
- * Used by TaskTool and analyze-file (commit agent).
- */
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { Snowflake } from "@nghyane/arcane-utils";
-import type { ModelRegistry } from "../config/model-registry";
-import { isDefaultModelAlias } from "../config/model-resolver";
-import type { Settings } from "../config/settings";
-import type { AuthStorage } from "../session/auth-storage";
-import { getBundledAgent } from "./agents";
-import { type ExecutorOptions, runAgent } from "./executor";
-import { mapWithConcurrencyLimit, type ParallelResult } from "./parallel";
-import type { AgentDefinition, SingleResult } from "./types";
-
-export interface BatchTask {
-	id: string;
-	description: string;
-	task: string;
-}
-
-export interface BatchOptions {
-	cwd: string;
-	agentName: string;
-	tasks: BatchTask[];
-	sessionFile: string | null;
-	signal?: AbortSignal;
-	authStorage?: AuthStorage;
-	modelRegistry?: ModelRegistry;
-	settings: Settings;
-	executorOverrides?: Partial<ExecutorOptions>;
-}
-
-export interface BatchResult {
-	results: ParallelResult<SingleResult>["results"];
-	aborted: boolean;
-	agent: AgentDefinition;
-	artifactsDir: string;
-	persistArtifacts: boolean;
-}
-
-export async function runTaskBatch(options: BatchOptions): Promise<BatchResult> {
-	const agent = getBundledAgent(options.agentName);
-	if (!agent) {
-		throw new Error(`Agent "${options.agentName}" not found.`);
-	}
-
-	const modelOverride = isDefaultModelAlias(agent.model) ? undefined : agent.model;
-
-	const sessionFile = options.sessionFile;
-	const artifactsDir = sessionFile ? sessionFile.slice(0, -path.extname(sessionFile).length) : null;
-	const tempArtifactsDir = artifactsDir ? null : path.join(os.tmpdir(), `arc-batch-${Snowflake.next()}`);
-	const effectiveArtifactsDir = artifactsDir || tempArtifactsDir!;
-	const persistArtifacts = !!artifactsDir;
-
-	await fs.mkdir(effectiveArtifactsDir, { recursive: true });
-
-	const maxConcurrency = options.settings.get("task.maxConcurrency");
-
-	try {
-		const result = await mapWithConcurrencyLimit(
-			options.tasks,
-			maxConcurrency,
-			async (task, index) =>
-				runAgent({
-					cwd: options.cwd,
-					agent,
-					task: task.task,
-					description: task.description,
-					index,
-					id: task.id,
-					modelOverride,
-					sessionFile,
-					persistArtifacts,
-					artifactsDir: effectiveArtifactsDir,
-					enableLsp: false,
-					signal: options.signal,
-					authStorage: options.authStorage,
-					modelRegistry: options.modelRegistry,
-					settings: options.settings,
-					...options.executorOverrides,
-				}),
-			options.signal,
-		);
-
-		return {
-			results: result.results,
-			aborted: result.aborted,
-			agent,
-			artifactsDir: effectiveArtifactsDir,
-			persistArtifacts,
-		};
-	} finally {
-		if (tempArtifactsDir) {
-			await fs.rm(tempArtifactsDir, { recursive: true, force: true });
-		}
-	}
-}

package/src/task/discovery.ts

@@ -1,126 +0,0 @@
-/**
- * Agent discovery from filesystem.
- *
- * Discovers agent definitions from:
- *   - ~/.arcane/agent/agents/*.md (user-level, primary)
- *   - ~/legacy)
- *   - ~/.claude/agents/*.md (user-level, legacy)
- *   - .arcane/agents/*.md (project-level, primary)
- *   - legacy)
- *   - .claude/agents/*.md (project-level, legacy)
- *
- * Agent files use markdown with YAML frontmatter.
- */
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { logger } from "@nghyane/arcane-utils";
-import { findAllNearestProjectConfigDirs, getConfigDirs } from "../config";
-import { listClaudePluginRoots } from "../discovery/helpers";
-import { loadBundledAgents, parseAgent } from "./agents";
-import type { AgentDefinition, AgentSource } from "./types";
-
-/** Result of agent discovery */
-export interface DiscoveryResult {
-	agents: AgentDefinition[];
-	projectAgentsDir: string | null;
-}
-
-/**
- * Load agents from a directory.
- */
-async function loadAgentsFromDir(dir: string, source: AgentSource): Promise<AgentDefinition[]> {
-	const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-	const files = entries
-		.filter(entry => (entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md"))
-		.sort((a, b) => a.name.localeCompare(b.name))
-		.map(file => {
-			const filePath = path.join(dir, file.name);
-			return fs
-				.readFile(filePath, "utf-8")
-				.then(content => parseAgent(filePath, content, source, "warn"))
-				.catch(error => {
-					logger.warn("Failed to read agent file", { filePath, error });
-					return null;
-				});
-		});
-
-	return (await Promise.all(files)).filter(Boolean) as AgentDefinition[];
-}
-
-/**
- * Discover agents from filesystem and merge with bundled agents.
- *
- * Precedence (highest wins): .arcane > .pi > .claude (project before user), then bundled
- *
- * @param cwd - Current working directory for project agent discovery
- */
-export async function discoverAgents(cwd: string, home: string = os.homedir()): Promise<DiscoveryResult> {
-	const resolvedCwd = path.resolve(cwd);
-	const agentSources = Array.from(new Set(getConfigDirs("", { project: false }).map(entry => entry.source)));
-
-	// Get user directories (priority order: .arcane, .pi, .claude, ...)
-	const userDirs = getConfigDirs("agents", { project: false })
-		.filter(entry => agentSources.includes(entry.source))
-		.map(entry => ({
-			...entry,
-			path: path.resolve(entry.path),
-		}));
-
-	// Get project directories by walking up from cwd (priority order)
-	const projectDirs = findAllNearestProjectConfigDirs("agents", resolvedCwd)
-		.filter(entry => agentSources.includes(entry.source))
-		.map(entry => ({
-			...entry,
-			path: path.resolve(entry.path),
-		}));
-
-	const orderedSources = agentSources.filter(
-		source => userDirs.some(entry => entry.source === source) || projectDirs.some(entry => entry.source === source),
-	);
-
-	const orderedDirs: Array<{ dir: string; source: AgentSource }> = [];
-	for (const source of orderedSources) {
-		const project = projectDirs.find(entry => entry.source === source);
-		if (project) orderedDirs.push({ dir: project.path, source: "project" });
-		const user = userDirs.find(entry => entry.source === source);
-		if (user) orderedDirs.push({ dir: user.path, source: "user" });
-	}
-
-	// Load agents from Claude Code marketplace plugins
-	const { roots: pluginRoots } = await listClaudePluginRoots(home);
-	const sortedPluginRoots = [...pluginRoots].sort((a, b) => {
-		if (a.scope === b.scope) return 0;
-		return a.scope === "project" ? -1 : 1;
-	});
-	for (const plugin of sortedPluginRoots) {
-		const agentsDir = path.join(plugin.path, "agents");
-		orderedDirs.push({ dir: agentsDir, source: plugin.scope === "project" ? "project" : "user" });
-	}
-
-	const seen = new Set<string>();
-	const loadedAgents = (await Promise.all(orderedDirs.map(({ dir, source }) => loadAgentsFromDir(dir, source))))
-		.flat()
-		.filter(agent => {
-			if (seen.has(agent.name)) return false;
-			seen.add(agent.name);
-			return true;
-		});
-
-	const bundledAgents = loadBundledAgents().filter(agent => {
-		if (seen.has(agent.name)) return false;
-		seen.add(agent.name);
-		return true;
-	});
-
-	const projectAgentsDir = projectDirs.length > 0 ? projectDirs[0].path : null;
-
-	return { agents: [...loadedAgents, ...bundledAgents], projectAgentsDir };
-}
-
-/**
- * Get an agent by name from discovered agents.
- */
-export function getAgent(agents: AgentDefinition[], name: string): AgentDefinition | undefined {
-	return agents.find(a => a.name === name);
-}