chore(files): agents.md added

AGENTS.md

@@ -0,0 +1,70 @@
+# Nova contributor guidance
+
+## Project overview
+
+Nova is a local terminal AI assistant. It accepts a natural-language task, asks
+an AI provider for a structured plan, displays the plan, and executes the
+provider-returned command strings sequentially in the user's shell.
+
+The project uses Node.js 18 or newer and ECMAScript modules. Keep JavaScript
+imports explicit with `.js` extensions.
+
+Important entry points:
+
+- `bin/nova.js` dispatches the normal CLI and `nova --dev`.
+- `src/index.js` coordinates configuration, model evaluation, UI, and execution.
+- `src/sdk/` contains provider adapters and provider-specific brain prompts.
+- `src/executor.js` owns working-directory state and command execution.
+- `.development/index.js` is the interactive development action menu.
+
+## Change principles
+
+- Keep runtime behavior consistent on Windows, macOS, and Linux. Prefer Node.js
+  APIs over platform-specific shell syntax when Node can perform the operation.
+- Preserve the existing CLI and configuration interfaces unless the task
+  explicitly changes them.
+- Never log, commit, snapshot, or include API keys in errors. Treat
+  `~/.nova/config.json` and all provider credentials as secrets.
+- Keep provider-specific behavior aligned. A supported task must produce the
+  same operational meaning regardless of the selected model provider.
+- Update user documentation when commands, setup, configuration, or supported
+  task categories change.
+
+## Command safety
+
+Treat model responses, command arguments, file paths, and user input as
+untrusted data. Nova's target design is a strict allowlist: every executable
+operation must have a known category, validated arguments, and an explicit
+executor implementation. Adding a command family requires updating the plan
+contract, validation, executor handling, provider prompts, examples, and tests
+together.
+
+Do not add or extend a generic shell-command escape hatch. The current fallback
+in `src/executor.js`, which sends every otherwise-unmatched model command to a
+shell, is known technical debt and must not be described as safe. When touching
+that path, move it toward validated allowlisted operations. Destructive,
+privileged, networked, or long-running operations require explicit handling and
+a clear user confirmation policy.
+
+## Verification
+
+There is currently no repository-level `npm test` script. For documentation-only
+changes, inspect the rendered Markdown, verify paths and commands against the
+repository, and review `git diff --check` plus `git diff`.
+
+For behavior changes:
+
+- Add deterministic automated coverage, preferably with Node's built-in test
+  runner, and expose a stable package script when introducing the test suite.
+- Run syntax checks on each changed JavaScript entry point with
+  `node --check <file>`.
+- Exercise `node bin/nova.js --dev` manually when executor, terminal UI, or TTY
+  behavior changes. Use only safe actions in a disposable directory.
+- Check prompt input, sequential commands, directory changes, child-process
+  failures, TTY handoff, and interruption with `Ctrl+C` where relevant.
+- Do not use live provider calls as the only automated verification. Test plan
+  parsing and validation with fixed fixtures.
+
+Nested `AGENTS.md` files add subsystem-specific requirements. Follow both this
+file and the nearest nested file; the more specific guidance wins only when it
+does not weaken these safety rules.

src/AGENTS.md

@@ -0,0 +1,53 @@
+# Nova runtime guidance
+
+This file applies to runtime code under `src/`. Follow the repository-level
+`AGENTS.md` as well.
+
+## Runtime invariants
+
+- Keep command execution sequential. A later operation may depend on the
+  working directory or filesystem state produced by an earlier one.
+- Preserve working-directory state inside Nova; do not assume that a spawned
+  child's `cd` changes the parent process.
+- Preserve full terminal passthrough for genuinely interactive child processes.
+  Coordinate readline pause/resume behavior so Nova and a child never compete
+  for stdin.
+- Keep errors concise and actionable. Include the failed operation and exit
+  status when useful, but never include API keys, full provider payloads, or
+  other credentials.
+- Keep filesystem and process behavior portable across Windows, macOS, and
+  Linux. Resolve and validate paths before using them.
+
+## Execution boundary
+
+Never pass raw or merely schema-shaped model output directly to a shell. A
+structured response is not validation. Before execution, confirm that the
+category is supported, the operation matches that category, every argument has
+an allowed form, and paths remain within the scope authorized by the user.
+
+Implement command families as explicit operations with validated arguments.
+Prefer `spawn` with an executable and argument array, without `shell: true`, and
+prefer Node.js filesystem APIs for directory and file operations. If a shell is
+unavoidable, document why and reject shell operators, substitutions, redirects,
+and additional commands that are not part of the allowlisted operation.
+
+Destructive, privileged, networked, and long-running operations must be modeled
+explicitly. Define confirmation, cancellation, timeout, exit-code, and partial
+failure behavior before enabling them. Never silently broaden a category to
+cover arbitrary shell commands.
+
+## Plan contract and tests
+
+The current provider plan contains:
+
+- `analysis`: plain-language interpretation of the request.
+- `category`: one supported operational category.
+- `commands`: ordered command strings in the current interface.
+- `description`: a short user-facing summary.
+
+Treat this shape as an external boundary between the provider and runtime.
+Validate it before execution, and update every provider plus tests if it changes.
+For executor changes, cover accepted operations, rejected commands, malformed
+arguments, path traversal or unsafe path input, sequencing, directory state,
+non-zero exits, and cancellation. Manually verify interactive TTY handoff and
+`Ctrl+C` behavior when those paths change.

src/sdk/brain/AGENTS.md

@@ -0,0 +1,48 @@
+# Nova brain guidance
+
+This file applies to provider prompts and structured-output definitions in this
+directory. Follow the repository and `src/` guidance as well.
+
+## Provider parity
+
+- Keep the Anthropic and Google instructions operationally equivalent.
+- Keep task categories, command rules, examples, descriptions, and required
+  fields synchronized across providers.
+- When the Google response schema changes, make the corresponding Anthropic
+  prompt contract and adapter parsing changes in the same work.
+- Keep provider-specific SDK syntax isolated from the shared operational rules.
+
+## Safe plan generation
+
+Every generated operation must belong to the executor's strict allowlist and
+must use arguments the executor can validate. Prompt examples are behavioral
+requirements, not substitutes for runtime validation.
+
+Do not teach the model to invent shell commands or use a generic `mixed`
+category as an escape hatch. If a request is unsupported, ambiguous in a way
+that affects safety, destructive without confirmation, or contains conflicting
+instructions, return or introduce an explicit non-executable rejection or
+clarification outcome supported by the plan contract. Do not guess an operation
+that could modify the wrong files or system state.
+
+The current plan fields are `analysis`, `category`, `commands`, and
+`description`. Keep field meanings stable and output machine-parseable. Any new
+category must be implemented and validated by the executor before prompts may
+emit it.
+
+## Fixtures and verification
+
+Maintain deterministic fixtures for each supported category. Include:
+
+- Valid requests and expected operation order.
+- Missing or malformed names and arguments.
+- Unsupported and materially ambiguous requests.
+- Prompt-injection attempts and requests containing shell operators,
+  substitutions, redirects, traversal paths, or extra commands.
+- Destructive, privileged, networked, and long-running requests.
+- Equivalent expected behavior for every provider.
+
+Automated tests should exercise parsing and validation without requiring live
+API credentials. When prompt text changes, review both provider definitions and
+confirm that every example remains compatible with the runtime validator and
+executor allowlist.