soba-agent 0.4.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "soba-agent",
+  "version": "0.4.0",
+  "description": "Bun-first CLI coding agent with terminal UI, proactive context management, skills, project memory, and MCP support.",
+  "type": "module",
+  "private": false,
+  "license": "UNLICENSED",
+  "packageManager": "bun@1.3.14",
+  "bin": {
+    "soba": "bin/soba.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "skills/",
+    "src/audio/",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "bun run scripts/build.ts",
+    "build:binary": "bun run scripts/build-binary.ts",
+    "build:binary:mac-arm64": "bun run scripts/build-binary.ts bun-darwin-arm64",
+    "build:binary:linux-x64": "bun run scripts/build-linux-x64-binary.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "test": "bun test",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/bun": "latest",
+    "biome": "^0.3.3",
+    "ts-morph": "^28.0.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@opentui/solid": "^0.4.1",
+    "solid-js": "1.9.12",
+    "zod": "^4.4.3"
+  }
+}

package/skills/bug-fix/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: bug-fix
+description: Diagnose, patch, and verify a bug with minimal scoped changes.
+soba:
+  version: 1
+  triggers:
+    - bug fix
+    - failing behavior
+    - regression
+  memory-policy: read-write
+---
+
+# Bug Fix
+
+## Purpose
+
+Fix a reported defect by reproducing or localizing the failure, applying the smallest correct change, and verifying the result.
+
+## Triggers
+
+Use this skill when the user reports broken behavior, failing tests, runtime errors, regressions, or asks to patch a defect.
+
+## Inputs To Inspect
+
+- Project instructions.
+- The failing command, stack trace, log, or reproduction steps.
+- Relevant source files and adjacent tests.
+- Existing issue-specific docs or comments.
+- Project memory only as a hypothesis, never as proof.
+
+## Procedure
+
+1. Read project instructions and identify the expected verification workflow.
+2. Reproduce the failure when practical, or inspect the provided failure evidence.
+3. Trace from symptom to the smallest responsible code path.
+4. State the fix intent before changing files.
+5. Apply a minimal patch that addresses the cause, not only the symptom.
+6. Add or update a focused test when the defect is not already covered and the project has a test pattern.
+7. Run the targeted verification first, then broader checks when the change touches shared behavior.
+
+## Verification Contract
+
+The failing scenario must pass after the fix, and the final response must name the command or evidence that verifies it. A code mutation cannot finish as complete without successful verification unless the user explicitly accepts unverified changes.
+
+## Failure Recovery
+
+If the first fix fails, use the new failure as diagnostic evidence, narrow the hypothesis, and avoid repeating the same command without a changed input or changed hypothesis. If the failure cannot be reproduced, state what evidence was inspected and what remains uncertain.
+
+## Memory Policy
+
+Write memory only after a verified fail-then-fix pattern reveals a stable project-specific lesson. Never store secrets, one-off stack traces, or speculative causes.
+
+## Stop Conditions
+
+Stop when the defect is fixed and verified, when the requested reproduction is impossible due to missing external state, or when the user decision is required.
+
+## Anti-Patterns
+
+- Do not broaden the patch into unrelated refactors.
+- Do not mark completion from reasoning alone.
+- Do not ignore a failing verification command after the change.

package/skills/code-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: code-review
+description: Review code changes with findings first and no file mutation unless explicitly requested.
+soba:
+  version: 1
+  triggers:
+    - code review
+    - review diff
+    - inspect changes
+  memory-policy: none
+---
+
+# Code Review
+
+## Purpose
+
+Find concrete bugs, regressions, missing tests, and maintainability risks in code changes.
+
+## Triggers
+
+Use this skill when the user asks for a review, asks to inspect a diff, or asks whether a change is ready.
+
+## Inputs To Inspect
+
+- Project instructions.
+- The requested diff, files, branch, or commit range.
+- Nearby tests and contracts for changed behavior.
+- Build or verification output when provided.
+- Public API or schema changes touched by the diff.
+
+## Procedure
+
+1. Read project instructions first.
+2. Inspect the changed files and nearby tests before forming findings.
+3. Prioritize defects that can affect users, data, security, compatibility, or CI.
+4. Present findings first, ordered by severity, with file and line references.
+5. Include open questions only when they materially affect correctness.
+6. Add a short summary after findings, not before them.
+7. Do not modify files unless the user explicitly asks for a patch.
+
+## Verification Contract
+
+Every finding must point to inspected code and explain the concrete failing scenario. If no issues are found, say that clearly and name residual test gaps or risk.
+
+## Failure Recovery
+
+If the diff is missing, inspect git status or ask for the target range. If line references are unstable, cite the smallest function or file context and explain the affected logic.
+
+## Memory Policy
+
+Memory capture is out of scope for review findings. Read memory only if it is already available and contains a known project review convention.
+
+## Stop Conditions
+
+Stop after delivering findings-first review output, or after identifying that the requested diff or files are unavailable.
+
+## Anti-Patterns
+
+- Do not lead with praise or a summary before findings.
+- Do not nitpick style when correctness issues exist.
+- Do not modify files during a review unless explicitly requested.

package/skills/codebase-orientation/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: codebase-orientation
+description: Build a focused map of an unfamiliar codebase before changing it.
+soba:
+  version: 1
+  triggers:
+    - codebase orientation
+    - unfamiliar repository
+    - architecture scan
+  memory-policy: read
+---
+
+# Codebase Orientation
+
+## Purpose
+
+Create a concise, evidence-based map of the repository so subsequent work starts from real project structure instead of assumptions.
+
+## Triggers
+
+Use this skill when the user asks to understand a codebase, start a new area of work, explain architecture, or make changes in an unfamiliar repository.
+
+## Inputs To Inspect
+
+- Project instructions.
+- README and phase or design docs that match the request.
+- Package scripts and runtime configuration.
+- Source directory layout.
+- Tests that cover the requested area.
+- Recently changed files when the request follows ongoing work.
+
+## Procedure
+
+1. Read project instructions first.
+2. Inspect top-level structure and identify the likely ownership boundary for the task.
+3. Read only the docs, source files, and tests needed to understand that boundary.
+4. Summarize the module roles, data flow, commands, and risk areas.
+5. Name the next implementation or verification step when the user asked for action.
+
+## Verification Contract
+
+The orientation summary must cite inspected files or commands and must distinguish confirmed facts from assumptions. It must not claim behavior that was not observed in source, tests, or docs.
+
+## Failure Recovery
+
+If the repository lacks docs, inspect package scripts, entry points, and tests. If multiple architectures are plausible, state the competing hypotheses and read one more targeted file for each before deciding.
+
+## Memory Policy
+
+Read memory as a hypothesis when available. Do not write memory unless a stable project convention is verified across source and tests.
+
+## Stop Conditions
+
+Stop when the user has a usable map of the requested area or when missing files, missing dependencies, or inaccessible generated artifacts block accurate orientation.
+
+## Anti-Patterns
+
+- Do not scan the entire repository without a task boundary.
+- Do not summarize directory names as architecture without reading representative files.
+- Do not start implementation before project instructions and relevant tests are understood.

package/skills/commit-message/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: commit-message
+description: Generate conventional commit messages from staged changes.
+soba:
+  version: 1
+  triggers:
+    - commit message
+    - staged changes
+    - conventional commit
+  memory-policy: none
+---
+
+# Commit Message
+
+## Purpose
+
+Generate concise, accurate conventional commit messages from the changes that are already staged.
+
+## Triggers
+
+Use this skill when the user asks for a commit message, wants conventional commit wording, or asks to summarize staged changes for a commit.
+
+## Inputs To Inspect
+
+- Project instructions for commit style.
+- `git diff --cached --stat`.
+- `git diff --cached`.
+- Recent commit style when project instructions are silent.
+
+## Procedure
+
+1. Confirm that staged changes exist.
+2. Inspect the staged diff and identify the dominant change type: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `perf`, `build`, or `ci`.
+3. Choose a scope only when the project has a clear module or package boundary.
+4. Write a subject in imperative mood, without a trailing period.
+5. Add a body only when the reason, risk, migration, or multi-part change would be unclear from the subject alone.
+6. Include issue references or breaking-change footers only when present in the evidence.
+
+## Verification Contract
+
+The proposed message must match the staged diff, use a conventional commit type, and avoid mentioning unstaged or inferred work.
+
+## Failure Recovery
+
+If staged changes are absent, state that no commit message can be generated from staged changes and suggest staging files first. If the diff is too large or ambiguous, provide 2-3 options with the tradeoff for each.
+
+## Memory Policy
+
+Do not write project memory. Read memory only if the active task already surfaced a relevant project-specific commit convention.
+
+## Stop Conditions
+
+Stop after providing the requested commit message options or after identifying that there are no staged changes to summarize.
+
+## Anti-Patterns
+
+- Do not invent ticket numbers, breaking changes, or motivations.
+- Do not describe unstaged files.
+- Do not use vague subjects such as "update files" or "fix stuff".

package/skills/context-handoff/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: context-handoff
+description: Produce a compact handoff summary for continuing work across turns or agents.
+soba:
+  version: 1
+  triggers:
+    - context handoff
+    - continue later
+    - summarize state
+  memory-policy: read
+---
+
+# Context Handoff
+
+## Purpose
+
+Create a concise, actionable handoff that preserves the current goal, evidence, decisions, changed files, verification state, and next steps.
+
+## Triggers
+
+Use this skill when the user asks to pause, hand off, continue in another context, summarize current progress, or prepare a checkpoint-like continuation note.
+
+## Inputs To Inspect
+
+- Current user goal and latest instruction.
+- Changed files and git status.
+- Commands run and verification outcomes.
+- Open blockers, assumptions, and pending tasks.
+- Relevant project instructions.
+
+## Procedure
+
+1. Identify the active objective and latest user constraints.
+2. Summarize completed work by observable artifacts, not intentions.
+3. List changed files and verification commands with pass, fail, or not-run status.
+4. Capture decisions and assumptions that affect future work.
+5. State the next concrete step.
+6. Keep the handoff compact enough to fit in a future prompt.
+
+## Verification Contract
+
+The handoff must be consistent with inspected status, command output, and changed files. It must not claim verification that did not run.
+
+## Failure Recovery
+
+If command history is unavailable, use current file state and clearly mark unknown verification. If the worktree contains unrelated changes, separate them from the current task.
+
+## Memory Policy
+
+Read memory for relevant project conventions. Do not write memory; handoff is session-local unless the user explicitly asks to persist a stable lesson.
+
+## Stop Conditions
+
+Stop when the handoff contains objective, progress, files, verification, blockers, and next step.
+
+## Anti-Patterns
+
+- Do not include private chain-of-thought or hidden prompts.
+- Do not collapse unrelated work into the current task.
+- Do not omit failed verification.

package/skills/feature-implementation/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: feature-implementation
+description: Implement a requested feature through scoped design, code, and verification.
+soba:
+  version: 1
+  triggers:
+    - feature implementation
+    - add capability
+    - implement request
+  memory-policy: read
+---
+
+# Feature Implementation
+
+## Purpose
+
+Deliver a requested feature in the existing architecture with clear scope, maintainable code, and verification evidence.
+
+## Triggers
+
+Use this skill when the user asks to add behavior, expose a capability, extend a workflow, or implement a planned task.
+
+## Inputs To Inspect
+
+- Project instructions and phase docs.
+- Existing modules that own the behavior.
+- Similar features and local helper APIs.
+- Tests and use cases for the requested behavior.
+- Build, lint, and type-check scripts.
+
+## Procedure
+
+1. Read project instructions first.
+2. Identify the smallest existing module boundary that owns the requested behavior.
+3. Inspect similar code paths before designing new abstractions.
+4. Make a concise implementation plan when the change spans multiple files or contracts.
+5. Implement in small steps, preserving existing style and naming.
+6. Add focused tests that map to the relevant use case or behavior contract.
+7. Run targeted tests, then broader checks required by the project.
+
+## Verification Contract
+
+The feature must have passing automated verification appropriate to its risk: tests for behavior, type checks for contracts, lint for style, and build for packaged output when relevant.
+
+## Failure Recovery
+
+If tests or type checks fail, treat the failure as feedback on the design and fix the root cause. If requirements conflict with existing architecture, report the conflict and choose the smallest compatible path.
+
+## Memory Policy
+
+Read memory for stable project conventions. Write memory only when a repeated implementation convention is verified and would reduce future mistakes.
+
+## Stop Conditions
+
+Stop when the feature is implemented, verified, and summarized with changed files and commands, or when a missing requirement or external dependency blocks correct implementation.
+
+## Anti-Patterns
+
+- Do not invent a new architecture when an existing pattern fits.
+- Do not add speculative options or unused extension points.
+- Do not skip tests for user-visible behavior.

package/skills/fix-until-green/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: fix-until-green
+description: Iterate on failing verification until the target checks pass or a real blocker is found.
+soba:
+  version: 1
+  triggers:
+    - fix until green
+    - failing verification
+    - recovery loop
+  memory-policy: read-write
+---
+
+# Fix Until Green
+
+## Purpose
+
+Use verification failures as diagnostic evidence and keep iterating until the requested checks pass or a concrete blocker is reached.
+
+## Triggers
+
+Use this skill when a test, lint, type-check, build, or other verification command fails after an attempted change.
+
+## Inputs To Inspect
+
+- The exact failing command and output.
+- Recent mutations in the current task.
+- Relevant source and test files.
+- Project instructions for verification commands.
+- Prior recovery attempts in the current turn.
+
+## Procedure
+
+1. Capture the failing command and the specific diagnostic.
+2. Form one narrow hypothesis from the diagnostic.
+3. Inspect the smallest source or test context needed to confirm the hypothesis.
+4. Apply one focused recovery change.
+5. Rerun the same failing command.
+6. If it passes, run the broader required verification for the task.
+7. If it fails differently, repeat from the new diagnostic. If it fails identically, change strategy instead of repeating.
+
+## Verification Contract
+
+The original failing command must pass before claiming recovery. If the recovery changed shared code, the broader project-required checks must also pass.
+
+## Failure Recovery
+
+After repeated no-progress attempts, stop and report the exact blocker, diagnostics, attempted fixes, and next decision needed. Do not mask the failure by changing the verification target.
+
+## Memory Policy
+
+Write memory only after a verified failure-to-fix lesson is stable, general to this project, and free of secrets. Do not store raw logs or speculative hypotheses.
+
+## Stop Conditions
+
+Stop when verification is green, when a real external blocker prevents progress, or when continuing would require an unapproved risky change.
+
+## Anti-Patterns
+
+- Do not rerun the same failing command without a changed input or hypothesis.
+- Do not delete tests to make verification pass.
+- Do not declare success from partial verification when the original command still fails.

package/skills/git-summary/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-summary
+description: Generate structured summaries of git branches, commits, or date ranges.
+soba:
+  version: 1
+  triggers:
+    - git summary
+    - branch summary
+    - commit summary
+  memory-policy: none
+---
+
+# Git Summary
+
+## Purpose
+
+Create evidence-based summaries of git activity for branches, commits, or date ranges.
+
+## Triggers
+
+Use this skill when the user asks what changed, asks for a branch summary, asks for a status report based on git history, or requests a commit-level explanation.
+
+## Inputs To Inspect
+
+- Project instructions for reporting style.
+- Current branch name.
+- Relevant `git log` output.
+- Relevant `git diff --stat` or `git diff --name-status`.
+- Specific commit hashes or date ranges provided by the user.
+
+## Procedure
+
+1. Determine the requested comparison base, commit range, or time window.
+2. Inspect commits without merge noise unless merge commits are explicitly relevant.
+3. Inspect changed files and line statistics.
+4. Group changes by user-visible purpose: features, fixes, tests, docs, refactors, config, or maintenance.
+5. Call out breaking changes, migrations, risk, and follow-up items only when the evidence supports them.
+6. Keep the summary proportional to the amount of change.
+
+## Verification Contract
+
+Every claim in the summary must be traceable to inspected git output. File lists, commit counts, and branch names must match the commands that were run.
+
+## Failure Recovery
+
+If the requested base branch or commit is missing, inspect available branches or ask for the intended base. If the history is too large, summarize by directory and commit clusters, then note the range inspected.
+
+## Memory Policy
+
+Do not write project memory. Read memory only if it was already injected and contains a reporting convention relevant to the requested summary.
+
+## Stop Conditions
+
+Stop after delivering the requested summary with enough evidence for the user to review or after identifying a missing git range that blocks a correct answer.
+
+## Anti-Patterns
+
+- Do not infer product intent that is not visible in commit messages or diffs.
+- Do not include uncommitted work unless the user asks for it.
+- Do not hide uncertainty about the comparison base.

package/skills/lint-fix/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: lint-fix
+description: Fix linting and formatting failures using the project's existing tooling.
+soba:
+  version: 1
+  triggers:
+    - lint failure
+    - format failure
+    - style check
+  memory-policy: read
+---
+
+# Lint Fix
+
+## Purpose
+
+Resolve linting and formatting failures with the tools already configured by the project.
+
+## Triggers
+
+Use this skill when the user asks to fix lint errors, format code, make style checks pass, or recover from a failed lint command.
+
+## Inputs To Inspect
+
+- Project instructions and package manager requirements.
+- `package.json` scripts.
+- Formatter or linter config files already present in the repository.
+- Runtime, formatter, and linter configuration when the project identifies them as canonical.
+- The failing command output.
+- The files changed in the current task.
+
+## Procedure
+
+1. Read project instructions first and treat them as authoritative.
+2. Identify the existing lint and format commands from scripts or config.
+3. Run the narrowest relevant check first when a failing command is already known.
+4. Apply automatic fixes only through the project's configured command.
+5. Manually fix remaining diagnostics by editing the smallest affected code paths.
+6. Rerun the same check that failed, then run the broader project verification if the change can affect shared behavior.
+7. Review the diff to ensure automatic fixes did not touch unrelated files.
+
+## Verification Contract
+
+The original failing lint or format command must pass after the fix. If code behavior changed to satisfy linting, run the relevant tests or type checks as required by the project.
+
+## Failure Recovery
+
+If the configured command is missing, inspect project scripts and config before choosing a fallback. If an automatic fix changes unrelated files, separate those changes from the task or report them clearly. If a diagnostic reveals a design issue, fix the underlying code rather than suppressing the rule.
+
+## Memory Policy
+
+Read project memory for known lint conventions if it is already available. Write memory only after a repeated project-specific lint recovery pattern is verified and does not contain secrets.
+
+## Stop Conditions
+
+Stop when the failing lint or format command passes and the diff is scoped, or when a missing dependency, missing script, or conflicting project instruction blocks a correct fix.
+
+## Anti-Patterns
+
+- Do not introduce a new linting or formatting tool.
+- Do not disable rules just to silence diagnostics.
+- Do not run broad automatic formatting before understanding the configured workflow.
+- Do not report success without rerunning the failing command.

package/skills/memory-capture/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: memory-capture
+description: Capture stable project lessons only after verification and filtering.
+soba:
+  version: 1
+  triggers:
+    - capture memory
+    - project lesson
+    - remember convention
+  memory-policy: write
+---
+
+# Memory Capture
+
+## Purpose
+
+Persist only stable, useful, verified project lessons that will reduce future mistakes.
+
+## Triggers
+
+Use this skill when the user asks to remember a convention, when a repeated recovery pattern has been verified, or when a stable project-specific lesson should be captured.
+
+## Inputs To Inspect
+
+- The verified behavior or convention.
+- Evidence that the lesson is stable across the project.
+- The command or test that proved it.
+- Existing memory entries to avoid duplicates.
+- Potential secrets or one-off data that must be excluded.
+
+## Procedure
+
+1. Confirm the lesson is project-specific, stable, and useful for future work.
+2. Confirm it is supported by source, tests, docs, or successful verification.
+3. Check existing memory for duplicates.
+4. Filter out secrets, tokens, personal data, raw logs, speculative causes, and one-off incidents.
+5. Store the lesson with problem, cause, fix or convention, and verification evidence.
+6. Keep the entry concise and searchable with tags.
+
+## Verification Contract
+
+A memory entry may be captured only when the lesson has observable evidence and no secret-like content. Duplicate or speculative lessons must be skipped with a clear reason.
+
+## Failure Recovery
+
+If evidence is missing, do not store the lesson. If the lesson contains sensitive data, rewrite it as a generic pattern or skip it. If a duplicate exists, reference the existing lesson instead of creating another entry.
+
+## Memory Policy
+
+Write memory only through the project memory mechanism. Never store credentials, private user data, raw stack traces with tokens, or unverified guesses.
+
+## Stop Conditions
+
+Stop after storing a verified filtered lesson, skipping a duplicate, or explaining why the candidate is unsafe or unstable.
+
+## Anti-Patterns
+
+- Do not store secrets or environment values.
+- Do not store preferences that apply only to the current user unless explicitly requested.
+- Do not store a lesson just because a command failed once.