hatch3r 1.8.0 → 1.9.0

package/prompts/hatch3r-bug-triage.md

@@ -1,158 +0,0 @@
----
-id: hatch3r-bug-triage
-type: prompt
-description: Triage a bug report and suggest investigation steps
-tags: [core]
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-# Bug Triage
-
-Triage the described bug and produce a structured investigation plan with severity classification, root cause hypotheses, and recommended fix approach.
-
-## Instructions
-
-1. **Classify severity** using the matrix below. Consider both user impact and data integrity risk.
-2. **Identify affected area** from the description — map to specific modules, services, or components.
-3. **Assess blast radius** — how many users are affected? Is data at risk? Are there downstream effects?
-4. **List 3–5 investigation steps** with specific files, functions, or logs to check. Order by likelihood of finding the root cause.
-5. **Suggest a minimal reproduction path** — exact steps a developer can follow to reproduce the bug locally.
-6. **Propose a fix approach** if the root cause is evident, including which files to change and what tests to add.
-7. **Flag related issues** — check for similar past bugs, related symptoms, or recent regressions.
-
-## Severity Matrix
-
-| Priority | Criteria | Response SLA | Examples |
-|----------|----------|-------------|----------|
-| **P0** | Data loss, security breach, complete service outage | Immediate (drop everything) | Credential leak, database corruption, auth bypass |
-| **P1** | Core feature broken, no workaround, significant user impact | Same day | Login fails, payments broken, data not saving |
-| **P2** | Feature degraded, workaround exists, moderate user impact | Within sprint | Slow page load, intermittent error, UI glitch on edge case |
-| **P3** | Cosmetic issue, minor inconvenience, low frequency | Backlog | Typo, alignment off by 1px, tooltip truncated |
-
-## Edge Cases to Consider
-
-- Is this a regression? Check recent deploys and PRs merged near the reported time.
-- Is this environment-specific? Different behavior in dev/staging/prod, different browsers, or different locales.
-- Is this timing-dependent? Race conditions, timezone issues, cache staleness.
-- Is this data-dependent? Specific user data, edge-case input values, empty/null states.
-- Is this intermittent? Flaky behavior suggests concurrency, caching, or external dependency issues.
-
-## Output Template
-
-```markdown
-## Bug Triage: {short title}
-
-### Classification
-
-| Field | Value |
-|-------|-------|
-| **Priority** | P0 / P1 / P2 / P3 |
-| **Affected Area** | {module / service / component} |
-| **Blast Radius** | {all users / subset / single user} |
-| **Regression?** | Yes (since {version/date}) / No / Unknown |
-| **Data at Risk?** | Yes ({what data}) / No |
-
-### Reproduction Steps
-
-1. {exact step}
-2. {exact step}
-3. {exact step}
-- **Expected:** {what should happen}
-- **Actual:** {what happens instead}
-- **Environment:** {browser, OS, locale, or server environment}
-
-### Investigation Plan
-
-| # | Step | Where to Look | What to Check |
-|---|------|---------------|---------------|
-| 1 | {action} | `{file:function}` | {what to look for} |
-| 2 | {action} | `{log source}` | {pattern or error message} |
-| 3 | {action} | `{git log / deploy history}` | {recent changes in area} |
-
-### Root Cause Hypotheses
-
-| Rank | Hypothesis | Likelihood | Evidence |
-|------|-----------|-----------|----------|
-| 1 | {most likely cause} | High / Med / Low | {supporting evidence} |
-| 2 | {alternative cause} | High / Med / Low | {supporting evidence} |
-
-### Recommended Fix
-
-- **Approach:** {description of fix}
-- **Files to change:** {list}
-- **Tests to add:** {regression test description}
-- **Rollback plan:** {if fix is risky}
-
-### Related Issues
-
-- #{N} — {title} ({similarity reason})
-```
-
-## Few-Shot Examples
-
-### Example 1: P0 Security Bug
-
-**Input:** "Users can see other users' billing information by changing the user ID in the URL."
-
-**Output:**
-
-```markdown
-## Bug Triage: IDOR in billing endpoint
-
-### Classification
-
-| Field | Value |
-|-------|-------|
-| **Priority** | P0 |
-| **Affected Area** | API — billing routes |
-| **Blast Radius** | All users with billing data |
-| **Regression?** | Unknown — check when `/api/billing/:userId` was added |
-| **Data at Risk?** | Yes — billing addresses, payment method last-4, invoice history |
-
-### Investigation Plan
-
-| # | Step | Where to Look | What to Check |
-|---|------|---------------|---------------|
-| 1 | Check auth middleware | `src/routes/billing.ts` | Is `requireAuth` applied? Does it verify `userId === req.user.id`? |
-| 2 | Check authorization | `src/middleware/auth.ts` | Is ownership validated, not just authentication? |
-| 3 | Check other user-scoped routes | `src/routes/*.ts` | Same pattern may exist elsewhere |
-
-### Recommended Fix
-
-- **Approach:** Add ownership check: `if (params.userId !== req.user.id) return 403`
-- **Files to change:** `src/routes/billing.ts`, `src/middleware/auth.ts` (add `requireOwnership` helper)
-- **Tests to add:** Test that user A cannot access user B's billing endpoint
-```
-
-### Example 2: P2 UI Bug
-
-**Input:** "Date picker shows wrong month when timezone is UTC-12."
-
-**Output:**
-
-```markdown
-## Bug Triage: Date picker timezone offset
-
-### Classification
-
-| Field | Value |
-|-------|-------|
-| **Priority** | P2 |
-| **Affected Area** | UI — DatePicker component |
-| **Blast Radius** | Users in far-west timezones (low frequency) |
-| **Regression?** | No — likely always present |
-| **Data at Risk?** | No — display only |
-
-### Investigation Plan
-
-| # | Step | Where to Look | What to Check |
-|---|------|---------------|---------------|
-| 1 | Check date construction | `src/components/DatePicker.ts` | Is `new Date()` used without timezone normalization? |
-| 2 | Check locale formatting | `src/utils/dates.ts` | Is `Intl.DateTimeFormat` using the correct timezone? |
-| 3 | Test with mocked timezone | `tests/unit/` | Set `TZ=Etc/GMT+12` and verify month calculation |
-
-### Recommended Fix
-
-- **Approach:** Normalize to UTC before extracting month/year for display
-- **Tests to add:** Parameterized test across UTC-12, UTC, UTC+14
-```

package/prompts/hatch3r-code-review.md

@@ -1,134 +0,0 @@
----
-id: hatch3r-code-review
-type: prompt
-description: Review code changes for quality, security, and correctness
-tags: [core]
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-# Code Review
-
-Review the provided code changes for quality, security, and correctness. Produce a structured review report with actionable feedback.
-
-## Instructions
-
-1. **Correctness** — Does the code do what it is supposed to? Verify against acceptance criteria, spec references, and expected behavior. Check for off-by-one errors, missing null/undefined handling, incorrect operator usage, and logic inversions.
-2. **Security** — Input validation at boundaries, auth checks on every route, no secrets in code or logs, CSRF protection on mutations, parameterized queries, safe deserialization. Flag any trust boundary violations.
-3. **Code Quality** — Naming follows conventions, functions < 50 lines, files < 400 lines, cyclomatic complexity ≤ 10, no dead code or unused imports, DRY without over-abstraction.
-4. **Type Safety** — No `any`, no `@ts-ignore` without a linked issue, discriminated unions preferred over type assertions, `satisfies` over `as` where applicable.
-5. **Performance** — No N+1 queries, no unnecessary allocations in hot paths, lazy loading for large imports, no unbounded list fetches, bundle size impact assessed.
-6. **Testing** — New logic has unit tests, bug fixes have regression tests, edge cases covered, mocks are minimal and focused.
-7. **Accessibility** — If UI changes: keyboard navigation, WCAG AA contrast (4.5:1), ARIA attributes, `prefers-reduced-motion` respected.
-8. **Error Handling** — Errors caught and handled at the appropriate level, user-facing errors are informative but safe (no stack traces), fail-closed defaults.
-
-## Edge Cases to Watch
-
-- Empty collections and null/undefined inputs at boundaries
-- Concurrent modifications and race conditions
-- Unicode and multi-byte string handling
-- Timezone-sensitive date operations
-- Large payload sizes and pagination exhaustion
-- Partial failures in batch operations
-
-## Severity Classification
-
-| Severity | Criteria | Action |
-|----------|----------|--------|
-| **Critical** | Security vulnerability, data loss risk, privacy violation, incorrect business logic | Must fix before merge |
-| **Warning** | Performance regression, missing tests, code quality violation, poor error handling | Should fix, PR author decides timing |
-| **Suggestion** | Naming improvement, alternative pattern, readability enhancement | Nice to have, not blocking |
-
-## Output Template
-
-```markdown
-## Code Review: {file or PR scope}
-
-**Verdict:** APPROVE | REQUEST CHANGES | COMMENT
-
-### Critical
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/auth.ts:42` | Missing token expiry check | Add `if (isExpired(token)) throw new AuthError(...)` |
-
-### Warnings
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/api/users.ts:78` | No test for empty input case | Add unit test for `getUser(undefined)` |
-
-### Suggestions
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/utils.ts:15` | `data` is vague | Rename to `userProfile` for clarity |
-
-### Summary
-
-- Critical: {n} | Warnings: {n} | Suggestions: {n}
-- Test coverage: {assessed / not assessed}
-- Security: {no issues / issues found}
-```
-
-## Few-Shot Examples
-
-### Example 1: Security Issue Found
-
-**Input:** A diff adding a new API endpoint:
-
-```typescript
-app.post("/api/admin/users", async (req, res) => {
-  const user = await db.createUser(req.body);
-  res.json(user);
-});
-```
-
-**Output:**
-
-```markdown
-## Code Review: src/routes/admin.ts
-
-**Verdict:** REQUEST CHANGES
-
-### Critical
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/routes/admin.ts:12` | No auth middleware on admin endpoint | Add `requireAuth("admin")` middleware before handler |
-| 2 | `src/routes/admin.ts:13` | `req.body` used without validation | Add zod schema: `const body = CreateUserSchema.parse(req.body)` |
-
-### Warnings
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/routes/admin.ts:14` | Full user object returned including password hash | Return `omit(user, ["passwordHash"])` |
-
-### Summary
-
-- Critical: 2 | Warnings: 1 | Suggestions: 0
-- Security: AUTH MISSING, INPUT UNVALIDATED
-```
-
-### Example 2: Clean Code with Minor Suggestions
-
-**Input:** A utility function refactor with tests.
-
-**Output:**
-
-```markdown
-## Code Review: src/utils/format.ts
-
-**Verdict:** APPROVE
-
-### Suggestions
-
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | `src/utils/format.ts:8` | `formatDate` accepts `any` | Use `Date | string | number` union type |
-
-### Summary
-
-- Critical: 0 | Warnings: 0 | Suggestions: 1
-- Test coverage: 4 new tests added, edge cases covered
-- Security: no issues
-```

package/prompts/hatch3r-pr-description.md

@@ -1,176 +0,0 @@
----
-id: hatch3r-pr-description
-type: prompt
-description: Generate a pull request description from staged changes
-tags: [core]
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-# PR Description
-
-Generate a pull request description for the current changes. Analyze the diff and produce a structured, reviewer-friendly PR description.
-
-## Instructions
-
-1. **Analyze the staged diff and recent commits** on this branch. Identify all files changed, lines added/removed, and the nature of each change.
-2. **Identify the type of change:**
-
-   | Type | Prefix | When to Use |
-   |------|--------|-------------|
-   | Feature | `feat:` | New functionality or capability |
-   | Fix | `fix:` | Bug fix or error correction |
-   | Refactor | `refactor:` | Code restructuring without behavior change |
-   | Docs | `docs:` | Documentation only |
-   | Test | `test:` | Adding or updating tests only |
-   | Infra | `infra:` | CI/CD, build config, tooling |
-   | Perf | `perf:` | Performance improvement |
-   | Security | `security:` | Security fix or hardening |
-
-3. **Write a concise title** following Conventional Commits: `{type}: {short description}` (max 72 characters).
-4. **Write the body** with structured sections (see template below).
-5. **Assess risk level** — low (docs, tests), medium (new feature, refactor), high (auth, data model, security).
-
-## Edge Cases to Handle
-
-- **Multiple change types:** If the PR spans types (e.g., feature + tests + docs), use the primary type and note others in the summary.
-- **Breaking changes:** Always include a `## Breaking Changes` section with migration instructions. Prefix title with `feat!:` or `fix!:`.
-- **Large PRs:** If the diff exceeds 500 lines, suggest splitting. List logical split points.
-- **No linked issue:** Flag this — every PR should reference an issue.
-- **Reverts:** Use `revert:` prefix and link to the original PR being reverted.
-
-## Output Template
-
-```markdown
-## {type}: {short description}
-
-### Summary
-
-- {what changed — 1-3 bullet points explaining the change and why it was needed}
-
-### Changes
-
-| File | Change | Description |
-|------|--------|-------------|
-| `{path}` | Added / Modified / Deleted | {what and why} |
-
-### Test Plan
-
-- [ ] {how to verify the changes work — specific steps}
-- [ ] {edge case verified}
-- [ ] Lint and typecheck pass
-- [ ] All tests pass
-
-### Risk Assessment
-
-| Factor | Level | Notes |
-|--------|-------|-------|
-| **Scope** | Low / Med / High | {number of files, modules touched} |
-| **Data impact** | None / Low / High | {any schema or data changes} |
-| **Security** | None / Low / High | {auth, input validation, secrets} |
-| **Rollback** | Easy / Complex | {can this be reverted cleanly?} |
-
-### Breaking Changes
-
-{None, or describe what breaks and how to migrate}
-
-### Related
-
-- Closes #{issue_number}
-- Related: #{other_issue}
-```
-
-## Few-Shot Examples
-
-### Example 1: Feature PR
-
-**Input:** Diff adds a new rate-limiting middleware, updates 3 route files, adds tests.
-
-**Output:**
-
-```markdown
-## feat: add rate limiting to public API endpoints
-
-### Summary
-
-- Add token-bucket rate limiter middleware to prevent abuse of public endpoints
-- Apply 100 req/min limit to auth endpoints, 1000 req/min to read endpoints
-- Return standard `429 Too Many Requests` with `Retry-After` header
-
-### Changes
-
-| File | Change | Description |
-|------|--------|-------------|
-| `src/middleware/rateLimiter.ts` | Added | Token-bucket implementation with Redis backing |
-| `src/routes/auth.ts` | Modified | Apply rate limiter with auth-tier limits |
-| `src/routes/api.ts` | Modified | Apply rate limiter with standard-tier limits |
-| `tests/unit/rateLimiter.test.ts` | Added | 8 tests covering burst, steady-state, and reset |
-
-### Test Plan
-
-- [ ] Verify 429 returned after exceeding limit
-- [ ] Verify `Retry-After` header is accurate
-- [ ] Verify rate limit resets after window expires
-- [ ] Load test confirms no false positives under normal traffic
-
-### Risk Assessment
-
-| Factor | Level | Notes |
-|--------|-------|-------|
-| **Scope** | Medium | 3 route files + new middleware |
-| **Data impact** | None | No schema changes |
-| **Security** | Low | Additive security improvement |
-| **Rollback** | Easy | Remove middleware from routes |
-
-### Breaking Changes
-
-None
-
-### Related
-
-- Closes #42
-```
-
-### Example 2: Bug Fix PR
-
-**Input:** Diff fixes an off-by-one error in pagination, adds a regression test.
-
-**Output:**
-
-```markdown
-## fix: correct off-by-one in cursor pagination
-
-### Summary
-
-- Fix pagination returning duplicate items when cursor falls on page boundary
-- Root cause: `>=` comparison should have been `>` in cursor offset calculation
-
-### Changes
-
-| File | Change | Description |
-|------|--------|-------------|
-| `src/db/pagination.ts` | Modified | Fix boundary comparison operator |
-| `tests/unit/pagination.test.ts` | Modified | Add regression test for boundary cursor |
-
-### Test Plan
-
-- [ ] Verify no duplicates at page boundary (regression test added)
-- [ ] Verify first page, last page, and empty result still work
-- [ ] Existing pagination tests still pass
-
-### Risk Assessment
-
-| Factor | Level | Notes |
-|--------|-------|-------|
-| **Scope** | Low | Single line fix + test |
-| **Data impact** | None | Read-only query change |
-| **Security** | None | No auth changes |
-| **Rollback** | Easy | Revert single commit |
-
-### Breaking Changes
-
-None
-
-### Related
-
-- Closes #87
-```

package/rules/hatch3r-observability-tracing-detail.md

@@ -1,20 +0,0 @@
----
-id: hatch3r-observability-tracing-detail
-type: rule
-description: "[Deprecated] AI agent tracing detail rule -- consolidated into hatch3r-observability-tracing's AI Agent Instrumentation section"
-scope: conditional
-globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/*agent*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
-tags: [devops]
-quality_charter: agents/shared/quality-charter.md
-deprecated: true
-cache_friendly: true
----
-# Observability -- Tracing Extended Reference (Deprecated Redirect)
-
-This rule has been merged into `hatch3r-observability-tracing`. Load that rule for AI agent instrumentation, tool call spans, LLM request/response tracing, tool call audit trails, and correlation ID patterns.
-
-- See `hatch3r-observability-tracing` § "AI Agent Instrumentation" for: GenAI span attributes, agent invocation spans, tool call spans, LLM request/response tracing, tool call audit trail, correlation IDs for agent workflows.
-
-<!-- DEPRECATED-CONTENT-REMOVED -->
-
-The full content has been migrated to `hatch3r-observability-tracing`.

package/rules/hatch3r-observability-tracing-detail.mdc

@@ -1,14 +0,0 @@
----
-description: "[Deprecated] AI agent tracing detail rule -- consolidated into hatch3r-observability-tracing's AI Agent Instrumentation section"
-globs: ["**/*trac*", "**/*span*", "**/*telemetry*", "**/*otel*", "**/*agent*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
-alwaysApply: false
----
-# Observability -- Tracing Extended Reference (Deprecated Redirect)
-
-This rule has been merged into `hatch3r-observability-tracing`. Load that rule for AI agent instrumentation, tool call spans, LLM request/response tracing, tool call audit trails, and correlation ID patterns.
-
-- See `hatch3r-observability-tracing` § "AI Agent Instrumentation" for: GenAI span attributes, agent invocation spans, tool call spans, LLM request/response tracing, tool call audit trail, correlation IDs for agent workflows.
-
-<!-- DEPRECATED-CONTENT-REMOVED -->
-
-The full content has been migrated to `hatch3r-observability-tracing`.

package/rules/hatch3r-observability.md

@@ -1,20 +0,0 @@
----
-id: hatch3r-observability
-type: rule
-description: "[Deprecated] Observability conventions -- split into hatch3r-observability-logging, hatch3r-observability-metrics, and hatch3r-observability-tracing"
-scope: conditional
-globs: "**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**,**/observability/**"
-tags: [devops]
-quality_charter: agents/shared/quality-charter.md
-deprecated: true
-cache_friendly: true
----
-# Observability (Deprecated Redirect)
-
-This rule has been split into three focused rules for maintainability:
-
-- **`hatch3r-observability-logging`** -- Structured logging and error reporting conventions
-- **`hatch3r-observability-metrics`** -- Metrics, SLO/SLI definitions, alerting, and dashboard standards
-- **`hatch3r-observability-tracing`** -- Distributed tracing, OpenTelemetry semantic conventions, AI agent instrumentation, and correlation IDs
-
-Load the specific rule that matches your task scope instead of this file.

package/rules/hatch3r-observability.mdc

@@ -1,14 +0,0 @@
----
-description: "[Deprecated] Observability conventions -- split into hatch3r-observability-logging, hatch3r-observability-metrics, and hatch3r-observability-tracing"
-globs: ["**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**", "**/observability/**"]
-alwaysApply: false
----
-# Observability (Deprecated Redirect)
-
-This rule has been split into three focused rules for maintainability:
-
-- **`hatch3r-observability-logging`** -- Structured logging and error reporting conventions
-- **`hatch3r-observability-metrics`** -- Metrics, SLO/SLI definitions, alerting, and dashboard standards
-- **`hatch3r-observability-tracing`** -- Distributed tracing, OpenTelemetry semantic conventions, AI agent instrumentation, and correlation IDs
-
-Load the specific rule that matches your task scope instead of this file.

package/skills/hatch3r-agent-customize/SKILL.md

@@ -1,23 +0,0 @@
----
-id: hatch3r-agent-customize
-description: Redirect to write agent persona, model, and apply-scope overrides under .hatch3r/agents/ -- use when tailoring a sub-agent for the current repository
-tags: [customize]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-redirect_to: hatch3r-customize
----
-# Agent Customization
-
-> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: agent`.
-
-For agent-specific reference (model resolution, protected agents, YAML schema), see the `hatch3r-agent-customize` command.
-
-## Rejected Merge Alternative (D16.3 add-vs-remove bias)
-
-Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
-
-1. **Preserves UX entry points.** Users typed `/h4tcher-agent-customize` or referenced the id `hatch3r-agent-customize` (per CHANGELOG.md, `website/docs/reference/configuration.md:325`, `docs/model-selection.md:158`) before consolidation. Deleting the id breaks those entry points without a redirect target.
-2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
-
-The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-cli-aichat/SKILL.md

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-aichat
-description: "Multi-provider LLM chat CLI with RAG and session memory. Use when RAG-enabled multi-provider conversational shell with saved session history; invoke `aichat`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
-tags: ["cli-tools", "ai", "opt-in"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: aichat
-  bin: aichat
-  tier: 3
-  category: ai
-  homepage: https://github.com/sigoden/aichat
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# aichat
-
-Multi-provider LLM chat CLI with RAG and session memory
-
-## When to Use
-
-Reach for `aichat` when the task is in the **ai** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-## Token Cost
-
-CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
-Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
-
-## Recipes
-
-```bash
-aichat 'explain this commit message' < commit.txt
-```
-One-shot prompt with stdin as the input payload.
-
-```bash
-aichat -r 'tech writer' 'rewrite as bullets' < draft.md
-```
-Apply a saved role (`~/.config/aichat/roles/tech-writer.md`) as the system prompt.
-
-```bash
-aichat --model claude-3-5-sonnet -e 'summarize' README.md
-```
-Pin the model and pass a file argument directly — `-e` executes the prompt non-interactively.
-
-```bash
-aichat --rag mydocs 'how do we configure auth?'
-```
-Query a pre-built RAG index over local documentation — runs embeddings locally, no remote indexer needed.
-
-```bash
-aichat --session refactor-plan
-```
-Resume a named session with persisted history — useful for multi-turn refinement loops.
-
-## Wrong Choice When
-
-- **Scripted Unix-style pipelines with a rich plugin ecosystem:** `hatch3r-cli-llm` (tier 2) has plugin support for templates, embeddings, and provider adapters not in aichat.
-- **Offline-only / fully local inference:** aichat supports Ollama backends but adds an unneeded abstraction; talk to Ollama's HTTP API directly via `curl`.
-- **CI batch tasks that benefit from `mods` pipe semantics:** `hatch3r-cli-mods` reads a single piped payload then exits — simpler for one-shot transforms.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, structured CI use |
-| `hatch3r-cli-mods` (tier 3) | Single-piped-payload transforms, Unix-pipe ergonomics |
-| Raw `curl` against Ollama / provider HTTP API | Maximum control, no client-side caching or session state |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v aichat
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install aichat
-```
-
-Homepage: https://github.com/sigoden/aichat