# AGENTS Guidelines
## Windows Environment Notice
- Prefer PowerShell (`pwsh`/`powershell`) when on Windows.
- Prefer using pwsh.exe to run `pnpm <script>` when on WSL2.
- WSL2 may be used for non-package-manager commands only (e.g., `rg`, `tar`). Avoid running Node builds in WSL due to OS mismatch.
- WSL2 cross-drive performance: accessing repos under `/mnt/c|d|e/...` goes through a filesystem bridge and can be slower for full scans. Prefer scoping to subtrees, excluding heavy folders, or running the same searches with native Windows binaries in PowerShell for large/iterative scans.
- Do not auto-run dependency installs. The user must run `pnpm install` in Windows PowerShell manually and then confirm completion.
- Do not modify `package.json`/lockfiles to add or update dependencies without explicit user approval. Propose dependencies in `/spec` or `/plan`, and ask the user to run `pnpm add <pkg>` (or `pnpm install`) and confirm.
- Do not call Unix text tools directly in PowerShell (e.g., `sed`, `awk`, `cut`, `head`, `tail`). Use PowerShell-native equivalents instead:
- `head` → `Select-Object -First N`
- `tail` → `Get-Content -Tail N`
- paging → `Out-Host -Paging` or `more`
- substitution/replace → `-replace` with `Get-Content`/`Set-Content`
## Tool Priority
- Filename search: `fd`.
- Text/content search: `rg` (ripgrep).
- AST/structural search: `sg` (ast-grep) — preferred for code-aware queries (imports, call expressions, JSX/TSX nodes).
### AST-grep Usage
- Announce intent and show the exact command before running complex patterns.
- Common queries:
- Find imports from `node:path` (TypeScript/TSX):
- `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
- Find CommonJS requires of `node:path`:
- `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
- Suggest rewrite (do not auto-apply in code unless approved):
- Search: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
- Proposed replacement: `import $$ from 'pathe'`
### Search Hygiene (fd/rg/sg)
- Exclude bulky folders to keep searches fast and relevant: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- Prefer running searches against a scoped path (e.g., `src`) to implicitly avoid vendor and VCS directories.
- Examples:
- `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
- `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grep typically respects `.gitignore`; target `src` to avoid scanning vendor folders:
- `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
- If needed, add ignore patterns to your ignore files rather than disabling ignores.
## Temporary Research Files
- Canonical location: store all temporary research artifacts (downloaded READMEs, API docs, scratch notes) under `docs/research/`.
- Do not place temporary files at the repository root or outside `docs/research/`.
- Commit policy: avoid committing temporary files unless they are necessary for traceability during `/spec` or `/plan`. If committed, keep the scope minimal and store them under `docs/` only.
- Naming: use descriptive names with date or task context (e.g., `docs/research/2025-09-11-wsl-notes.md`).
- Cleanup: after completing a task (`/do`), evaluate whether each temporary file is still required. Remove unneeded files, or promote essential content into curated docs under `docs/` or into `specs/`/`plans/`.
## Stage-Gated Workflow (spec/plan/do)
- Mode: Opt-in. The workflow applies only when the user explicitly uses `/spec`, `/plan`, or `/do`. Routine Q&A or trivial edits do not require these stages.
- Triggers: A message containing one of `/spec`, `/plan`, or `/do` activates or advances the workflow. Once active, stages must proceed in order with explicit user approval to advance.
- Guardrails:
- Do not modify source code before `/do`. Documentation/spec files may be edited only in `/spec`.
- Do not skip stages or proceed without user confirmation once the workflow is active.
- If scope changes, return to the appropriate prior stage for approval.
- Respect sandbox/approval settings for all actions.
- When to Use
- Use the workflow for new features, structural refactors, multi-file changes, or work needing traceability.
- Skip the workflow (no triggers) for routine Q&A, diagnostics, or one-off trivial edits.
- Entry Points and Prerequisites
- `/spec` is the canonical entry point for new efforts.
- `/plan` requires an approved `/spec`. If unclear which spec applies, pause and ask the user to identify the correct file(s) under `specs/`.
- `/do` requires an approved `/plan`.
- `/spec` (Specifications; docs only)
- Purpose: Capture a concrete, reviewable specification using spec-kit style.
- Output: Markdown spec(s) under `specs/` (no code changes). Share a concise diff summary and links to updated files; wait for approval.
- Style: Specs are canonical and final. Do not include change logs or “correction/更正” notes. Incorporate revisions directly so the document always reflects the current agreed state. Historical context belongs in PR descriptions, commit messages, or the conversation — not in the spec.
- Recommended contents:
- Problem statement and context
- Goals and non-goals
- Requirements and constraints (functional, UX, performance, security)
- UX/flows and API/IPC contracts (as applicable)
- Acceptance criteria and success metrics
- Alternatives considered and open questions
- Rollout/backout considerations and telemetry (if relevant)
- `/plan` (High-level Plan; docs only)
- Purpose: Turn the approved spec into an ordered, verifiable implementation plan.
- Inputs: Approved spec file(s) in `specs/`.
- Ambiguity: If the relevant spec is unclear, pause and request clarification before writing the plan.
- Style: Plans are canonical and should not include change logs or “correction/更正” notes. Incorporate revisions directly so the plan always reflects the current agreed state. Historical notes should live in PR descriptions, commit messages, or the conversation.
- Output:
- An ordered plan via `update_plan` (short, verifiable steps; Task is merged into Plan and tracked here).
- A plan document in `plans/` named `YYYY-MM-DD-short-title.md`, containing:
- Scope and links to authoritative spec(s)
- Assumptions and out-of-scope items
- Phases/milestones mapped to acceptance criteria
- Impacted areas, dependencies, risks/mitigations
- Validation strategy (tests/lint/build) and rollout/backout notes
- Approval status and next stage
- Handoff: Await user approval of the plan before `/do`.
- `/do` (Execution)
- Purpose: Implement approved plan steps with minimal, focused changes and file operations.
- Actions:
- Use `apply_patch` for file edits; group related changes and keep diffs scoped to approved steps.
- Provide concise progress updates and a final summary of changes.
- Validate appropriately: run `pnpm lint`, `pnpm format`, `pnpm build`, and relevant tests.
- If material changes to the plan are needed, pause and return to `/plan` (or `/spec`) for approval.
- Output: Implemented changes, validation results, and a concise change summary linked to the plan checklist.
### Plans Directory
- Location: `plans/` at the repository root.
- Filename: `YYYY-MM-DD-short-title.md` (kebab-case title; consistent dating).
- Style: Plan docs are the canonical source of truth for the implementation approach; avoid embedding change logs or “correction/更正” notes. Update the plan in place as decisions evolve.
- Contents:
- Title and summary
- Scope and linked specs (paths under `specs/`)
- Assumptions / Out of scope
- Step-by-step plan (short, verifiable)
- Validation strategy (tests/lint/build)
- Approval status and next stage
- Process:
- During `/plan`, create or update the relevant file in `plans/` and share a short summary in the conversation. Await approval before `/do`.
