buildwithnexus 0.10.4 → 0.10.7

package/harness/src/bundled_skills/code-review.md

@@ -0,0 +1,17 @@
+# Code Review
+
+Use this skill when reviewing changes, auditing a PR, or checking for regressions.
+
+## Workflow
+
+1. Use `run_command` with `git status`, `git diff`, and `git diff --staged`.
+2. Use `read_file` for files where line context matters.
+3. Prioritize findings by severity.
+4. Mention tests that were not run or risk that remains.
+
+## Findings standard
+
+- Lead with bugs, security risks, data loss risks, broken UX, or missing tests.
+- Cite file paths and exact behavior.
+- Do not pad the review with style preferences.
+- If no issues are found, say that clearly and list residual test gaps.

package/harness/src/bundled_skills/codebase-repair.md

@@ -0,0 +1,32 @@
+# Codebase Repair
+
+Use this skill when the user asks to fix a bug, implement a feature, clean up a regression, or investigate failing behavior in a repository.
+
+## Tool workflow
+
+1. Start with `list_dir`, `find_files`, and `grep_files` to understand the codebase shape.
+2. Use `read_file` before `edit_file` or `write_file`; edits to existing files are expected to be read first.
+3. Prefer `grep_files` and `find_files` over shell search when they are enough.
+4. Use `run_command` for project-native checks such as `cargo test`, `cargo clippy`, `npm test`, `npm run build`, `git diff`, and package-specific scripts.
+5. Use `finish` only after implementation and verification are complete, or after explaining a real blocker.
+
+## Repair discipline
+
+- Keep changes scoped to the reported behavior.
+- Match existing style before adding abstractions.
+- Add or update tests when behavior changes.
+- If a check fails, inspect the error and fix the cause rather than masking it.
+- When a terminal/TUI bug is involved, use a PTY or real terminal path for validation where possible.
+- If Computer Use cannot operate the Terminal app, say so plainly and provide local terminal commands for manual verification.
+
+## Standard verification
+
+For Rust CLI work, prefer:
+
+- `cargo test --manifest-path harness/Cargo.toml`
+- `cargo clippy --manifest-path harness/Cargo.toml --all-targets --locked -- -D warnings`
+
+For npm package work, prefer:
+
+- `npm pack --dry-run`
+- installing from the local tarball in a temporary directory when package contents matter.

package/harness/src/bundled_skills/data-analysis.md

@@ -0,0 +1,16 @@
+# Data Analysis
+
+Use this skill for CSV/JSON/log analysis, metrics summaries, benchmark interpretation, or report generation.
+
+## Workflow
+
+1. Use `file_info`, `read_file`, and `read_many_files` to inspect inputs.
+2. Use `run_command` with existing tools such as `jq`, `awk`, `python3`, or project scripts when available.
+3. Use `write_file` for derived CSV/JSON/Markdown outputs.
+4. Use `create_docx` for a Word-ready summary when requested.
+
+## Standards
+
+- Preserve raw data; write derived outputs separately.
+- Explain assumptions and missing data.
+- Include reproducible commands or scripts when analysis is non-trivial.

package/harness/src/bundled_skills/decision_support.md

@@ -0,0 +1,59 @@
+# Decision Support
+
+When asked to evaluate a design decision, architecture choice, or strategic question, follow this structured workflow. Do NOT answer from intuition alone.
+
+## Workflow
+
+1. **Classify the decision**
+   - What type? (architecture, implementation, deployment, security, data model, dependency, process)
+   - What scope? (single file, module, service, system-wide)
+   - What urgency? (blocking, important, can-defer)
+
+2. **Gather evidence** — call these tools BEFORE forming an opinion:
+   - `search` / `grep`: Find relevant code, configs, and docs
+   - `read_file`: Read architecture decisions, README, existing implementations
+   - `glob`: Map the affected file/module structure
+   - `bash`: Run `git log` for history, check CI status, list dependencies
+
+3. **Identify constraints** — document what limits the decision:
+   - Existing API contracts
+   - Database schema dependencies
+   - Team capacity and operational maturity
+   - Security and compliance requirements
+   - Performance requirements
+   - Timeline pressures
+
+4. **Evaluate options** — for each option:
+   - Describe the approach
+   - List evidence supporting it
+   - List evidence against it
+   - Assess: risk, cost, reversibility, blast radius
+   - Note assumptions made
+
+5. **Apply decision rules**:
+   - If the change shares lifecycle, data, and failure domain → prefer extending existing
+   - If different scaling, security, or release needs → consider separation
+   - If team lacks operational maturity → avoid fragmentation
+   - If critical path → require feature flags and staged rollout
+   - If dependency is unmaintained → avoid adding
+   - If data is destructive → require rollback plan
+
+6. **Produce a decision memo** with these sections:
+   - **Recommendation**: clear, actionable statement
+   - **Rationale**: why this option, grounded in evidence
+   - **Evidence**: what was inspected (files, tests, docs, history)
+   - **Tradeoffs**: what you gain and what you give up
+   - **Risks**: what could go wrong and mitigations
+   - **Assumptions**: what you assumed but couldn't verify
+   - **Confidence**: high/medium/low with explanation
+   - **Next actions**: concrete steps to implement the decision
+
+## Rules
+
+- Never recommend without inspecting relevant code and docs first
+- Always state your confidence level
+- Always list assumptions
+- If evidence is missing, say so explicitly
+- Prefer reversible decisions when confidence is medium or low
+- If the decision could cause data loss, require a rollback plan
+- If the decision affects security boundaries, flag for security review

package/harness/src/bundled_skills/document-generation.md

@@ -0,0 +1,29 @@
+# Document Generation
+
+Use this skill when creating `.docx`, Markdown reports, user guides, runbooks, handoff docs, release notes, or executive summaries.
+
+## Tools
+
+- Use `create_docx` for simple Word documents.
+- Use `write_file` for Markdown, plain text, JSON, or CSV artifacts.
+- Use `read_many_files` to gather source material.
+- Use `fetch_url` or `web_search` only when the document needs current external facts.
+
+## DOCX guidance
+
+The built-in `create_docx` tool supports a title and markdown-like body:
+
+- `# Heading`
+- `## Heading`
+- `### Heading`
+- `- bullet`
+- blank lines
+- paragraphs
+
+For complex layout, tables, images, tracked changes, or strict corporate templates, say that native output is basic and generate a Markdown source plus DOCX if useful.
+
+## Writing standard
+
+- Lead with the answer.
+- Use short sections and concrete headings.
+- Avoid invented citations. If factual claims depend on current information, use web tools and cite URLs in the document text.

package/harness/src/bundled_skills/frontend-ux.md

@@ -0,0 +1,18 @@
+# Frontend UX
+
+Use this skill for web UI, TUI, CLI UX, onboarding, forms, dashboards, and user-facing flows.
+
+## Workflow
+
+1. Use `list_tree`, `grep_files`, and `read_many_files` to identify framework and design conventions.
+2. Prefer existing components and styles.
+3. For CLI/TUI UX, verify key handling, resize behavior, scrollback, alternate screen, and visible feedback.
+4. For standalone browser games, canvas demos, prototypes, or simple static pages, load `/static-app` and publish a runnable HTML artifact.
+5. Use `start_server` for local dev servers; call `wait_for_url` to prove readiness; inspect `read_server_log` for failures; use `open_browser` when a preview is useful.
+
+## Standards
+
+- Build the actual usable workflow, not a placeholder page.
+- For static browser deliverables, ship a runnable artifact rather than code pasted into chat.
+- Keep controls predictable and dense enough for repeated use.
+- Avoid hidden state: important hooks, tools, subagents, errors, and queued input need visible evidence.

package/harness/src/bundled_skills/git-release.md

@@ -0,0 +1,23 @@
+# Git And Release
+
+Use this skill for commit hygiene, npm package release prep, GitHub CI repair, and deployment-oriented changes.
+
+## Git discipline
+
+- Inspect `git status` before staging.
+- Do not revert unrelated user changes.
+- Keep commits scoped and authored with the configured repository identity.
+- For this project, release commits should use `geaglin09 <geaglin09@gmail.com>`.
+
+## Version discipline
+
+- Do not ask users to retest a version they already reported as broken.
+- Bump `package.json`, `harness/Cargo.toml`, and `harness/Cargo.lock` together.
+- Verify the npm package does not include unrelated build artifacts.
+- Next.js is not a CLI dependency.
+
+## Verification
+
+- Use `cargo test --manifest-path harness/Cargo.toml`.
+- Use `cargo clippy --manifest-path harness/Cargo.toml --all-targets --locked -- -D warnings`.
+- Use `npm pack --dry-run` to inspect package contents before publishing.

package/harness/src/bundled_skills/release-notes.md

@@ -0,0 +1,17 @@
+# Release Notes
+
+Use this skill when writing changelogs, release notes, migration notes, npm package descriptions, or PR summaries.
+
+## Workflow
+
+1. Use `run_command` with `git log`, `git diff`, and `git status`.
+2. Use `read_file` for package metadata and README changes.
+3. Group notes by user-visible areas: Added, Changed, Fixed, Removed, Security.
+4. Include upgrade notes and compatibility warnings.
+5. Use `write_file` to update changelog/release artifacts when asked.
+
+## Standard
+
+- Do not list internal refactors unless they matter to users.
+- Mention version numbers and package names exactly.
+- Include verification commands that passed.

package/harness/src/bundled_skills/research.md

@@ -0,0 +1,17 @@
+# Research
+
+Use this skill when answering questions that require current facts, comparing tools, investigating docs, or grounding a recommendation.
+
+## Workflow
+
+1. Use `web_search` to find candidate sources.
+2. Use `fetch_url` for primary sources and official documentation.
+3. Use `read_file` for local repo context before applying external guidance.
+4. Summarize what is known, what is inferred, and what remains uncertain.
+
+## Standards
+
+- Prefer official docs, source repositories, standards, and primary research.
+- Do not overquote sources.
+- If the answer could be outdated, use web tools.
+- For implementation work, translate findings into concrete repo changes.

package/harness/src/bundled_skills/rust-cli.md

@@ -0,0 +1,26 @@
+# Rust CLI Engineering
+
+Use this skill for Rust command-line, TUI, process, filesystem, packaging, or cross-platform terminal work.
+
+## Tool workflow
+
+- Use `read_file` on `Cargo.toml`, relevant modules, and tests before editing.
+- Use `grep_files` for symbol discovery and `find_files` for module layout.
+- Use `run_command` for `cargo fmt`, `cargo test`, `cargo check`, and `cargo clippy`.
+- Use `edit_file` for surgical changes; use `write_file` for new modules or tests.
+
+## TUI rules
+
+- Alternate screen behavior must emit enter and leave sequences in interactive mode.
+- Raw mode must be restored on exit, including error paths.
+- Composer rendering must not steal the output cursor from streaming assistant text.
+- Key handling should use terminal events, not line-buffered stdin, when raw mode is active.
+- Shift+Tab is commonly reported as backtab; handle it separately from Tab completion.
+- PTY tests are preferred for alternate screen and raw input behavior.
+
+## Rust quality
+
+- Avoid panics on user-controlled input and terminal dimensions.
+- Keep JSON payloads structured with `serde_json::json!`.
+- Clip or truncate large tool/hook outputs before storing or rendering them.
+- Make clippy happy under `-D warnings`.

package/harness/src/bundled_skills/security-review.md

@@ -0,0 +1,19 @@
+# Security Review
+
+Use this skill for threat modeling, dependency risk, command execution risk, hook/plugin safety, credential handling, and prompt-injection-sensitive workflows.
+
+## Workflow
+
+1. Use `grep_files` for risky patterns: secrets, shell execution, network fetches, deserialization, path traversal, auth, permissions.
+2. Use `read_many_files` for security-critical flows.
+3. Use `run_command` for native scanners only if already installed or configured by the repo.
+4. Use `todo_write` to track threat model areas.
+
+## Review checklist
+
+- Inputs are validated before filesystem, shell, or network actions.
+- Paths are normalized and sensitive locations are protected.
+- Hooks and commands are visible/auditable.
+- Credentials are not logged, traced, or sent to non-HTTPS endpoints.
+- Permission gates cover mutating and destructive operations.
+- External content cannot silently instruct the agent to run unsafe commands.

package/harness/src/bundled_skills/self-knowledge.md

@@ -0,0 +1,104 @@
+# Self-Knowledge
+
+Use this skill whenever the user asks how buildwithnexus works, reports a bug in buildwithnexus, asks you to repair or extend buildwithnexus itself, or asks about TUI behavior, hooks, tool calls, subagents, skills, memory, sessions, npm packaging, or local model setup.
+
+## What buildwithnexus is
+
+buildwithnexus is a Rust CLI agent harness. The npm package is a thin Node launcher that resolves or builds the Rust binary; Next.js is not part of the CLI runtime.
+
+Core Rust modules:
+
+- `src/lib.rs`: CLI routing, interactive REPL, slash commands, session lifecycle.
+- `src/tui.rs`: alternate screen, raw-mode input, persistent composer, Shift+Tab mode cycling, typeahead, streaming renderer.
+- `src/agent.rs`: PLAN, BUILD, and BRAINSTORM orchestration, tool loops, subagents, context compaction, permission gates.
+- `src/tools.rs`: built-in tool definitions and implementations.
+- `src/hooks.rs`: Claude Code-compatible lifecycle hooks.
+- `src/trace.rs`: navigable trace ledger for hooks, tools, skills, and subagents.
+- `src/config.rs`: settings, memory, skills, commands, hooks discovery, provider presets.
+- `src/provider.rs`: provider protocols, completions, streaming, tool-call parsing.
+- `src/session.rs`: saved session history, resume, continue.
+- `src/checkpoint.rs`: edit checkpoints and undo.
+- `src/onboarding.rs`: init/setup flow, including local model choices.
+- `src/report.rs`: human and JSON event reporting.
+
+## Actual built-in tools
+
+The agent can call these tools through model tool calls:
+
+- `read_file`
+- `read_many_files`
+- `list_dir`
+- `list_tree`
+- `file_info`
+- `find_files`
+- `grep_files`
+- `write_file`
+- `edit_file`
+- `multi_edit`
+- `apply_patch`
+- `create_dir`
+- `move_path`
+- `remove_path`
+- `run_command`
+- `todo_write`
+- `todo_read`
+- `create_docx`
+- `finish`
+- `save_memory`
+- `fetch_url`
+- `web_search`
+- `spawn_subagent` in BUILD mode
+
+The model should use these tools directly. It should not claim access to unavailable external tools unless it invokes them through `run_command` and verifies they exist.
+
+## Repair workflow
+
+When fixing buildwithnexus itself:
+
+1. Reproduce with the local Rust binary first:
+   `cargo run --manifest-path harness/Cargo.toml -- <args>`
+2. Prefer PTY tests for TUI behavior because alternate-screen, raw mode, cursor save/restore, Shift+Tab, and composer behavior require a terminal.
+3. If Computer Use cannot operate the Terminal app, say that explicitly. Do not claim a visual Terminal E2E was completed.
+4. Keep fixes in Rust unless the issue is specifically the npm launcher or docs.
+5. Run:
+   `cargo test --manifest-path harness/Cargo.toml`
+   `cargo clippy --manifest-path harness/Cargo.toml --all-targets --locked -- -D warnings`
+6. For npm install issues, verify the package contents with:
+   `npm pack --dry-run`
+
+## TUI expectations
+
+The interactive UI should:
+
+- Enter the terminal alternate screen on launch and leave it on exit.
+- Keep shell scrollback hidden while the TUI is active.
+- Use raw-mode key handling for Shift+Tab, Tab completion, history, editor shortcuts, and multiline input.
+- Keep a persistent composer at the bottom row.
+- Preserve output cursor position when rendering queued typeahead into the composer.
+- Surface trace rows when tools, hooks, skills, and subagents are used.
+- Let the user inspect trace details with `/trace` and `/trace <id>`.
+
+## Hook and trace expectations
+
+Hooks should capture:
+
+- Event name: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`.
+- Trigger payload, including tool name/input where applicable.
+- Hook source: home or project.
+- Matcher.
+- Command or script path.
+- Exit code, stdout, stderr.
+- Deny/allow decisions when present.
+
+Tools and subagents should capture:
+
+- Tool name, input, result, error state, phase, and depth.
+- Subagent task, role, isolate setting, working directory, and result.
+- Loaded skills and Agents.md context with enough preview to debug why the model had that context.
+
+## Packaging rules
+
+- Bump `package.json`, `harness/Cargo.toml`, and `harness/Cargo.lock` together for a release.
+- Ensure commits are authored as `geaglin09 <geaglin09@gmail.com>`.
+- The npm package should not depend on Next.js.
+- Do not ask users to retest a version they already reported as broken; cut a new version.

package/harness/src/bundled_skills/spec-writing.md

@@ -0,0 +1,19 @@
+# Spec Writing
+
+Use this skill when the user asks for a product spec, implementation plan, technical design, PRD, RFC, acceptance criteria, or issue-ready task breakdown.
+
+## Workflow
+
+1. Use `read_file`, `read_many_files`, `list_tree`, and `grep_files` to understand the existing product and architecture.
+2. Use `todo_write` for multi-section specs.
+3. Write specs with clear sections: problem, goals, non-goals, users, behavior, UX/API contract, data model, rollout, risks, tests, open questions.
+4. Use `write_file` for Markdown specs in `docs/`, `.buildwithnexus/`, or the repo’s established planning location.
+5. Use `create_docx` when the user asks for Word/docx output.
+
+## Quality bar
+
+- Make requirements testable.
+- Separate decisions from open questions.
+- Include concrete acceptance criteria.
+- Name migration and compatibility risks.
+- Keep implementation details aligned with the codebase, not generic architecture advice.

package/harness/src/bundled_skills/static-app.md

@@ -0,0 +1,36 @@
+# Static App and Canvas Game
+
+Use this skill when the user asks for a small website, standalone browser app, canvas game, playable demo, visualization, animation, or prototype that can run without a build step.
+
+## Output Contract
+
+- Build the actual runnable thing, not an explanation.
+- Prefer a single self-contained HTML file with embedded CSS and JavaScript unless the user explicitly asks for a framework.
+- Use `Artifact` or `publish_artifact` with `type: "html"` for standalone deliverables.
+- After publishing, use `open_browser` when possible so the user can try it immediately.
+- Never respond with source code only in markdown when the task asks you to build the app.
+
+## Canvas Game Standard
+
+A canvas game should include:
+
+- A visible play field that resizes to the viewport without clipping.
+- Keyboard controls and touch/mobile controls when practical.
+- A start or ready state, active play state, pause state, game-over state, and restart path.
+- Score/progress feedback and clear collision or failure feedback.
+- A real animation loop using `requestAnimationFrame`.
+- No placeholder art or unimplemented TODO sections.
+
+## Quality Bar
+
+- Use cohesive visual styling, not a plain default canvas on a white page.
+- Keep all text readable on mobile and desktop.
+- Avoid external CDN dependencies for simple games and demos.
+- If the user names a theme loosely, choose a good one and build immediately.
+- Include concise usage instructions inside the artifact only when they help the user play or operate it.
+
+## Verification
+
+- If a browser opener is available, call `open_browser` on the artifact path.
+- If the app needs a local server, call `start_server`, call `wait_for_url` to prove the URL responds, inspect `read_server_log` on failure, then call `open_browser` with the local URL.
+- If browser launch fails because the environment has no GUI, report the artifact path and the exact command to open or serve it.

package/harness/src/bundled_skills/test-engineering.md

@@ -0,0 +1,18 @@
+# Test Engineering
+
+Use this skill for adding tests, debugging failing checks, designing test plans, or improving coverage.
+
+## Workflow
+
+1. Use `grep_files` to find existing tests for the affected behavior.
+2. Use `read_many_files` to compare implementation and nearby tests.
+3. Add focused regression tests before or with the fix.
+4. Use `run_command` to run the narrowest relevant test first, then the broader suite.
+5. Record multi-step test work with `todo_write`.
+
+## Test strategy
+
+- Cover the behavior that failed, not incidental implementation.
+- Prefer deterministic tests over sleeps and network calls.
+- For TUI behavior, use PTY tests when possible.
+- For package/deployment behavior, test package contents or build output, not just source state.

package/harness/src/bundled_skills/tool-use.md

@@ -0,0 +1,52 @@
+# Tool Use
+
+Use this skill whenever the task requires acting through buildwithnexus tools.
+
+## Available tools
+
+- `read_file`: read UTF-8 files, optionally with `start_line` and `end_line`.
+- `read_many_files`: read several related text files in one call.
+- `list_dir`: list directory entries.
+- `list_tree`: recursively list a bounded tree.
+- `file_info`: inspect file or directory metadata.
+- `find_files`: recursively find files by simple glob pattern.
+- `grep_files`: literal text search with optional file pattern.
+- `write_file`: create or overwrite a file.
+- `edit_file`: replace one unique text occurrence in a file.
+- `multi_edit`: apply several exact replacements to one file.
+- `Artifact` / `publish_artifact`: Publish a structured document, webpage, SVG, diagram, or dataset.
+- `str_replace_editor` / `text_editor_20241022` / `text_editor_20250124`: A unified tool for viewing, creating, and editing files natively.
+- `AskUserQuestion`: Present the user with an interactive multiple-choice or written question.
+- `apply_patch`: apply a unified diff through `git apply`.
+- `create_dir`, `move_path`, `remove_path`: basic filesystem mutation.
+- `run_command`: run shell commands and return output.
+- `todo_write`, `todo_read`: maintain a structured task list.
+- `create_docx`: create a simple Word Document (.docx) from title and body. Do NOT use for HTML or code.
+- `fetch_url`: HTTP GET for a specific URL.
+- `web_search`: DuckDuckGo-backed web search.
+- `headless_browser`: fetch and extract readable page text and links.
+- `start_server`, `list_servers`, `wait_for_url`, `read_server_log`, `stop_server`: manage and verify long-running local dev servers. Use these instead of `run_command` for `npm run dev`, Vite, Next, Python, Rails, Cargo web servers, and similar watch/dev processes.
+- `open_browser`: open a local URL or generated HTML artifact in the user's default browser.
+- `save_memory`: persist durable user preferences or facts.
+- `spawn_subagent`: delegate a self-contained task to a fresh agent context.
+- `finish`: complete the task with a short summary.
+
+## Tool Discipline
+
+- **Mandatory Tool Usage:** Whenever generating or editing code, HTML, or any file contents, you MUST use the appropriate tool (e.g., `Artifact`, `str_replace_editor`, `write_file`). NEVER just write the code in plain markdown as your text response.
+- **Runnable Artifacts:** For canvas games, standalone browser apps, demos, and simple web pages, publish a complete static HTML artifact with `Artifact` / `publish_artifact`; then use `open_browser` when possible.
+- **No Placeholders:** When using file modification tools or `Artifact`, the contents MUST be fully implemented code or text. DO NOT use placeholders like `// canvas game logic here`.
+
+- **No Permission Seeking:** DO NOT ask the user for permission, themes, or layout choices. If instructions are open-ended, make a reasonable decision and just build it.
+## Choosing tools
+
+- Read/search/list tools are the default first step.
+- Use `run_command` for native project commands and checks.
+- Use `start_server` for long-running dev servers; use `wait_for_url` to prove readiness, and `read_server_log` to diagnose failures.
+- Use `fetch_url` for a known page and `web_search` when the target page is unknown or current information is needed.
+- Use `spawn_subagent` only for clearly separable work, such as independent research or a parallel audit.
+- Use mutating tools only after understanding the current file contents.
+
+## Evidence
+
+Tool calls, results, hook executions, skills, and subagents are visible in the TUI trace. Use `/trace` to list events and `/trace <id>` to inspect inputs, triggers, outputs, and decisions.

package/harness/src/bundled_skills/verification_workflow.md

@@ -0,0 +1,62 @@
+# Verification Workflow
+
+When implementing code changes (bug fixes, features, refactors), follow this constrained workflow. Do NOT edit files immediately.
+
+## Before Writing Code
+
+1. **Understand the scope**
+   - Search the repo for relevant files: `search` for keywords
+   - Read the affected code: `read_file` on key files
+   - Map the call graph: `grep` for callers of affected functions
+   - Check existing tests: `glob` for test files, `read_file` to review them
+
+2. **Identify constraints**
+   - Check for public API contracts that must not break
+   - Check for database schema dependencies
+   - Check for naming and error-handling conventions
+   - Check for existing CI configuration
+   - Check git history for related changes: `bash git log --oneline -10 -- <file>`
+
+3. **Reproduce the issue** (for bug fixes)
+   - Read the test suite for the affected area
+   - If possible, write a failing test first
+   - Confirm the failure before fixing
+
+## Writing Code
+
+4. **Apply the smallest safe fix**
+   - Do not change public API behavior unless required
+   - Prefer narrow patches over broad rewrites
+   - Do not weaken validation to fix parsing bugs
+   - Respect existing naming and error-handling conventions
+   - Do not introduce new runtime dependencies unless justified
+
+5. **Add or update tests**
+   - Every bug fix MUST include a regression test
+   - Every new feature MUST include unit tests
+   - Tests should cover the happy path AND edge cases
+
+## After Writing Code
+
+6. **Verify the change**
+   - Run the relevant test suite: `bash` with the project's test command
+   - Check for lint/format issues if a linter is configured
+   - Review the diff for unintended changes
+
+7. **Summarize the change**
+   - Root cause (for bugs)
+   - Files affected
+   - Fix strategy
+   - Tests added or changed
+   - Validation result (tests pass/fail)
+   - Residual risk (what could still go wrong)
+
+## Rules
+
+- A bug fix without a regression test is INCOMPLETE
+- Do not claim a fix is complete until tests pass
+- If a change touches authentication, flag for security review
+- If a migration is destructive, require a rollback strategy
+- If a function is public, search for all callers before changing its contract
+- If logs might contain secrets, block the change
+- If the change adds a dependency, check license and maintenance status