@nghyane/arcane 0.1.0

package/src/prompts/tools/reviewer.md

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,51 @@
+# 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

@@ -0,0 +1,28 @@
+<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

@@ -0,0 +1,275 @@
+# Task
+
+Launch subagents to execute parallel, well-scoped tasks.
+
+## What subagents inherit automatically
+Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. Do NOT repeat project rules, coding conventions, or style guidelines in `context` — they already have them.
+
+## What subagents do NOT have
+Subagents have no access to your conversation history. They don't know:
+- Decisions you made but didn't write down
+- Which approach you chose among alternatives
+- What you learned from reading files during this session
+- Requirements the user 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 and context files in their system prompt. Repeating them wastes tokens and inflates context. Restating any rule from AGENTS.md in `context` is a bug — treat it like a lint error.
+</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 → it's a project rule → the subagent already has it → delete the line.
+
+WRONG — restating project rules the subagent already has:
+```
+## Constraints
+- Use X import style, not Y (per AGENTS.md)
+- Use Z for private fields per AGENTS.md
+- Run the formatter after changes
+- Follow the logging convention
+```
+Every line above restates a project convention. The subagent reads AGENTS.md. Delete them all.
+
+RIGHT — only session-specific decisions the subagent cannot infer from project files:
+```
+## Constraints
+- We decided to use approach A over B (session decision)
+- The migration target type is `Foo` from `bar` package (looked up this session)
+```
+
+Use template; omit non-applicable sections:
+
+````
+## Goal
+One sentence: batch accomplishes together.
+
+## Non-goals
+Explicitly exclude tempting scope — what tasks must not touch/attempt.
+
+## 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
+- `path/to/other.ext` — reuse or avoid
+
+## API Contract (if tasks produce/consume shared interface)
+```language
+// Exact type definitions, function signatures, interface shapes
+```
+
+## Acceptance (global)
+- Definition of "done" for batch
+- Note: build/test/lint verification happens AFTER all tasks complete — not inside tasks (see below)
+````
+**Belongs in `context`**: task-specific goal, non-goals, session decisions, reference paths, shared type definitions, API contracts, global acceptance commands — anything 2+ tasks need that isn't already in AGENTS.md.
+**Rule of thumb:** if repeat in 2+ tasks, belongs in `context`.
+**Does NOT belong in `context`**: project rules already in AGENTS.md/context files, per-task file lists, one-off requirements (go in `assignment`), and strict response contracts that only apply to one task.
+
+### `tasks` (required)
+
+Array tasks execute in parallel.
+
+|Field|Required|Purpose|
+|---|---|---|
+|`id`|✓|CamelCase identifier, max 32 chars|
+|`description`|✓|Short one-liner for UI display only — not seen by subagent|
+|`assignment`|✓|Complete per-task instructions. See [Writing an assignment](#writing-an-assignment).|
+|`skills`||Skill names preload. Use only when changes correctness — don’t spam every task.|
+
+Outputs are free-form text/JSON from each subtask. If you need strict structure, define it clearly inside each `assignment` and validate at the caller.
+---
+
+## Writing an assignment
+
+<critical>## Task scope
+
+`assignment` must contain enough info for agent to act **without asking a clarifying question**.
+**Minimum bar:** assignment under ~8 lines or missing acceptance criteria = too vague. One-liners guaranteed failure.
+
+Use structure every assignment:
+
+```
+## Target
+- Files: exact path(s)
+- Symbols/entrypoints: specific functions, types, exports
+- Non-goals: what task must NOT touch (prevents scope creep)
+
+## Change
+- Step-by-step: add/remove/rename/restructure
+- Patterns/APIs to use; reference files if applicable
+
+## Edge Cases / Don't Break
+- Tricky case 1: ...
+- Tricky case 2: ...
+- Existing behavior must survive: ...
+
+## Acceptance (task-local)
+- Expected behavior or observable result
+- DO NOT include project-wide build/test/lint commands (see below)
+```
+
+`context` carries shared background. `assignment` carries only delta: file-specific instructions, local edge cases, per-task acceptance checks. Never duplicate shared constraints across assignments.
+
+### Anti-patterns (ban these)
+**Vague assignments** — agent guesses wrong or stalls:
+- "Refactor this to be cleaner."
+- "Migrate to N-API."
+- "Fix the bug in streaming."
+- "Update all constructors in `src/**/*.ts`."
+**Vague context** — forces agent invent conventions:
+- "Use existing patterns."
+- "Follow conventions."
+- "No WASM."
+**Redundant context** — wastes tokens repeating what subagents already have:
+- Restating AGENTS.md rules (coding style, import conventions, formatting commands, logger usage, etc.)
+- Repeating project constraints from context files
+- Listing tool/framework preferences already documented in the repo
+
+If a constraint appears in AGENTS.md, it MUST NOT appear in `context`. The subagent has the full system prompt.
+
+If tempted to write above, expand using templates.
+**Test/lint commands in parallel tasks** — edit wars:
+Parallel agents share working tree. If two agents run `bun check` or `bun test` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. **Never tell parallel tasks run project-wide build/test/lint commands.** Each task edits, stops. Caller verifies after all tasks complete.
+**If you can't specify scope yet**, create **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
+
+### Delegate intent, not keystrokes
+
+Your role as tech lead: set direction, define boundaries, call out pitfalls — then get out of way. Don’t read every file, decide every edit, dictate line-by-line. That makes you bottleneck; agent typist.
+**Be specific about:** constraints, naming conventions, API contracts, "don’t break" items, acceptance criteria.
+**Delegate:** code reading, approach selection, exact edit locations, implementation details. Agent has tools, can reason about code.
+
+Micromanaging (you think, agent types):
+```
+assignment: "In src/api/handler.ts, line 47, change `throw err` to `throw new ApiError(err.message, 500)`.
+On line 63, wrap fetch call try/catch return 502 on failure.
+On line 89, add null check before accessing resp.body..."
+```
+
+Delegating (agent thinks within constraints):
+```
+assignment: "## Target\n- Files: src/api/handler.ts\n\n## Change\nImprove error handling: replace raw throws
+with typed ApiError instances, add try/catch around external calls, guard against null responses.\n\n
+## Edge Cases / Don't Break\n- Existing error codes in tests must still match\n
+- Don't change public function signatures"
+```
+
+First style wastes your time, brittle if code shifts. Second gives agent room to do work.
+</critical>
+
+## Example
+
+<example type="bad" label="Duplicated context inflates tokens">
+<tasks>
+  <task name="Grep">
+    <description>Port grep module from WASM to N-API...</description>
+    <assignment>Port grep module from WASM to N-API... (same blob repeated)</assignment>
+</task>
+</tasks>
+</example>
+
+<example type="good" label="Shared rules in context, only deltas in assignment">
+<context>
+## Goal
+Port WASM modules to N-API, matching existing arcane-natives conventions.
+
+## Non-goals
+Do not touch TS bindings or downstream consumers — separate phase.
+
+## Constraints
+- MUST use `#[napi]` attribute macro on all exports
+- MUST return `napi::Result<T>` for fallible ops; never panic
+- MUST use `spawn_blocking` for filesystem I/O or >1ms work
+...
+
+## Acceptance (global)
+- Caller verifies after all tasks: `cargo test -p arcane-natives` and `cargo build -p arcane-natives` with no warnings
+- Individual tasks must NOT run these commands themselves
+</context>
+
+<tasks>
+  <task name="PortGrep">
+    <description>Port grep module to N-API</description>
+    <assignment>
+## Target
+- Files: `src/grep.rs`, `src/lib.rs` (registration only)
+- Symbols: search, search_multi, compile_pattern
+
+## Change
+- Implement three N-API exports in grep.rs:
+  - `search(pattern: JsString, path: JsString, env: Env) -> napi::Result<Vec<Match>>`
+...
+
+## Acceptance (task-local)
+- Three functions exported with correct signatures (caller verifies build after all tasks)
+</assignment>
+</task>
+
+  <task name="PortHighlight">
+    <description>Port highlight module to N-API</description>
+    <assignment>
+## Target
+- Files: `src/highlight.rs`, `src/lib.rs` (registration only)
+...
+</assignment>
+</task>
+</tasks>
+</example>
+---
+
+## Task scope
+
+Each task small, well-defined scope — **at most 3–5 files**.
+**Signs task too broad:**
+- File paths use globs (`src/**/*.ts`) instead of explicit names
+- Assignment says "update all" / "migrate everything" / "refactor across"
+- Scope covers entire package or directory tree
+**Fix:** enumerate files first (grep/glob discovery), 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** → run sequentially (A completes, then launch B with A 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 export names/signatures|
+|Scaffold structure|Implement bodies|Bodies need shape|
+|Core module|Dependent modules|Dependents import from core|
+|Schema/DB migration|Application logic|Logic depends on new schema shape|
+
+### Safe to parallelize
+- Independent modules, no cross-imports
+- Tests for already-implemented code
+- Isolated file-scoped refactors
+- Documentation for stable APIs
+
+### Phased execution
+
+Layered work with dependencies:
+**Phase 1 — Foundation** (do yourself or single task): define interfaces, create scaffolds, establish API shape. Never fan out until contract known.
+**Phase 2 — Parallel implementation**: fan out tasks consuming same known interface. Include Phase 1 API contract in `context`.
+**Phase 3 — Integration** (do yourself): wire modules, fix mismatches, verify builds.
+**Phase 4 — Dependent layer**: fan out tasks consuming Phase 2 outputs.
+---
+
+## Pre-flight checklist
+
+Before calling tool, verify:
+- [ ] `context` includes only session-specific info not already in AGENTS.md/context files
+- [ ] Each `assignment` follows assignment template — not one-liner
+- [ ] Each `assignment` includes edge cases / "don’t break" items
+- [ ] Tasks truly parallel (no hidden dependencies)
+- [ ] Scope small, file paths explicit (no globs)
+- [ ] No task runs project-wide build/test/lint — you do after all tasks complete

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

@@ -0,0 +1,65 @@
+# 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 in real time
+   - Mark complete IMMEDIATELY after finishing (no batching)
+   - Keep exactly ONE task in_progress at a time
+   - Remove tasks no longer relevant
+   - Complete tasks in list order (do not mark later tasks completed while earlier tasks remain incomplete)
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,19 @@
+# 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

@@ -0,0 +1,18 @@
+# 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>