From ed5cb94d37947a4b36e85d46be944a82c4472fbb Mon Sep 17 00:00:00 2001 From: ivanmaierg Date: Mon, 11 May 2026 19:31:09 -0300 Subject: [PATCH 1/2] chore(seo): restore npm metadata and README header - package.json: add description, keywords, license, repository, homepage, bugs fields (mirrors GitHub topics and description). - README.md: add subtitle blockquote and badges row above the existing first paragraph. Recovers metadata wiped from working tree during a prior reset. GitHub description and topics were already set and remain unchanged. --- README.md | 8 ++++++++ package.json | 28 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/README.md b/README.md index c02b6ef..e94a254 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,13 @@ # verbum +> Read the Bible from your terminal. A TUI + CLI scripture reader, in one binary. + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Bun](https://img.shields.io/badge/Bun-1.2+-black?logo=bun)](https://bun.sh) +[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![Architecture](https://img.shields.io/badge/architecture-hexagonal-7C3AED)](docs/architecture.md) +[![Status](https://img.shields.io/badge/status-design%20phase-orange)](#) + A TUI + CLI Bible reader. Built on **Hexagonal (Ports & Adapters)** with a **Screaming** top-level structure, so the API, the TUI, or the runtime can be swapped without touching the domain. > **Status:** design phase. The architecture, roadmap, user flows, and decision records are complete. Source code lands with v1. diff --git a/package.json b/package.json index 0158eac..41a9911 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,34 @@ { "name": "verbum", "version": "0.1.0", + "description": "Read the Bible from your terminal — TUI + CLI in one binary, built with Bun, TypeScript, OpenTUI, and Hexagonal Architecture.", + "keywords": [ + "bible", + "bible-reader", + "bible-cli", + "bible-tui", + "scripture", + "verse", + "tui", + "cli", + "terminal", + "terminal-ui", + "bun", + "typescript", + "react", + "opentui", + "hexagonal-architecture", + "clean-architecture" + ], + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/ivanmaierg/verbum.git" + }, + "homepage": "https://github.com/ivanmaierg/verbum#readme", + "bugs": { + "url": "https://github.com/ivanmaierg/verbum/issues" + }, "type": "module", "scripts": { "test": "bun test", From 522425b4a343ac9d5bea830e0b24334364cbf0e3 Mon Sep 17 00:00:00 2001 From: ivanmaierg Date: Mon, 11 May 2026 19:37:44 -0300 Subject: [PATCH 2/2] chore(atl): update skill registry and add local skill directory - .gitignore: include .atl/ to ignore local skill registry files. - .atl/skill-registry.md: enhance documentation with updated scanning sources, user skills, and compact rules for agent delegation. Added new skills and clarified usage for sub-agents. --- .atl/skill-registry.md | 294 +++++++++++++++++++++++++++++++---------- .gitignore | 3 + 2 files changed, 224 insertions(+), 73 deletions(-) diff --git a/.atl/skill-registry.md b/.atl/skill-registry.md index 2ce5907..e82eb0b 100644 --- a/.atl/skill-registry.md +++ b/.atl/skill-registry.md @@ -1,85 +1,233 @@ # Skill Registry — verbum -Last scanned: 2026-05-09 -Source: `~/.claude/skills/` (user-level) + `` system block +**Delegator use only.** Any agent that launches sub-agents reads this registry to resolve compact rules, then injects them directly into sub-agent prompts. Sub-agents do NOT read this registry or individual SKILL.md files. + +Last scanned: 2026-05-11 +Sources scanned: +- `~/.claude/skills/` (13 user skills) +- `~/.cursor/skills/` (1 user skill) +- `~/.claude/plugins/cache/` (installed plugin skills) +- `~/.config/opencode/skills/`, `~/.gemini/skills/`, `~/.copilot/skills/` (empty or absent) +- `{project}/.claude/skills/`, `.gemini/skills/`, `.agent/skills/`, `skills/` (none in verbum) + +Skipped per scan rules: `sdd-*`, `_shared`, `skill-registry`. + +--- ## User Skills -| Name | Trigger | Compact Rules | -|---|---|---| -| cognitive-doc-design | Writing guides, READMEs, RFCs, architecture docs, onboarding | Lead with the answer; progressive disclosure; chunking; signposting; recognition over recall (tables, checklists); review empathy | -| chained-pr | PRs over 400 lines, stacked PRs, review slices | Split oversized changes into chained PRs that protect review focus | -| comment-writer | PR feedback, issue replies, GitHub/Slack comments | Warm, direct collaboration tone; not sycophantic; not aggressive | -| work-unit-commits | Implementation, commit splitting, chained PRs | Plan commits as reviewable work units; keep tests and docs with the code that motivates them | -| go-testing | Go tests, teatest, golden files | Focused Go testing patterns. **Skip for verbum** — TS-only project. | -| skill-creator | New skills, agent instructions, AI usage patterns | LLM-first skill structure; valid frontmatter; trigger-first descriptions ≤ 250 chars | -| branch-pr | Creating, opening, preparing PRs | Issue-first checks; conventional commit titles | -| judgment-day | Dual review, adversarial review | Blind dual review, fix confirmed issues, then re-judge | -| issue-creation | GitHub issues, bug reports, feature requests | Issue-first checks before opening | -| ui-skills | Building interfaces with agents | Opinionated constraints for better interfaces | -| rams | Accessibility, visual design review | A11y + visual design review checklist | -| web-interface-guidelines | UI code review | Vercel Web Interface Guidelines compliance | -| simplify | Code review for reuse, quality, efficiency | Find duplicate logic, over-abstraction, dead code; fix issues found | -| fewer-permission-prompts | Reduce permission prompts | Add prioritized allowlist to project `.claude/settings.json` | -| claude-api | Anthropic SDK, prompt caching, model migrations | Build/optimize Claude API apps; include prompt caching by default | -| explain-blockers | Architectural blockers, "explain", "trade-offs" | Unpack blockers in plain language with What/Why/Fork/Instinct shape | -| sharpen-scope | Vague new work, /sdd-new, "let's build X" | Push back until Intent, First Reviewable Cut, Success Criterion, Riskiest Unknown are sharp | -| update-config | Hooks, permissions, env vars, settings.json | Configure Claude Code harness via settings.json; hooks for automation | -| keybindings-help | Customize keyboard shortcuts | Edit `~/.claude/keybindings.json` | -| init | Initialize CLAUDE.md | Generate codebase documentation file | -| review | Review a pull request | Standard PR review workflow | -| security-review | Security review of pending changes | Security-focused review of branch diff | -| loop | Recurring tasks, polling | `/loop 5m /foo` runs prompt on interval; omit interval for self-paced | -| schedule | Cron-scheduled remote agents | Routines that execute on cron; one-time scheduled runs supported | - -## Plugin Skills - -| Plugin | Skill | Purpose | +| Trigger | Skill | Path | |---|---|---| -| engram | memory | **Always active.** Persistent memory protocol — save decisions, conventions, bugs, discoveries proactively | -| claudebeat | pick / settings | Configure notification sounds (not relevant to verbum dev) | +| Audit a deployed URL or local web project against Vercel's Agent Readability spec | agent-readability-inspector | `~/.claude/skills/agent-readability-inspector/SKILL.md` | +| Create PRs with issue-first checks | branch-pr | `~/.claude/skills/branch-pr/SKILL.md` | +| Split PRs over 400 lines, stacked PRs, review slices | chained-pr | `~/.claude/skills/chained-pr/SKILL.md` | +| Writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs | cognitive-doc-design | `~/.claude/skills/cognitive-doc-design/SKILL.md` | +| PR feedback, issue replies, reviews, Slack/GitHub comments | comment-writer | `~/.claude/skills/comment-writer/SKILL.md` | +| Unpack architectural blockers in plain language; "explain", "trade-offs" | explain-blockers | `~/.claude/skills/explain-blockers/SKILL.md` | +| Go tests, teatest, golden files | go-testing | `~/.claude/skills/go-testing/SKILL.md` (**skip for verbum** — TS-only) | +| Creating GitHub issues, bug reports, or feature requests | issue-creation | `~/.claude/skills/issue-creation/SKILL.md` | +| Judgment day, dual review, adversarial review, juzgar | judgment-day | `~/.claude/skills/judgment-day/SKILL.md` | +| Improve repo SEO, add topics/keywords, repo discoverability | repo-seo | `~/.claude/skills/repo-seo/SKILL.md` | +| Force precision before new work; auto-fires on /sdd-new and vague scope | sharpen-scope | `~/.claude/skills/sharpen-scope/SKILL.md` | +| Create new skills with valid frontmatter | skill-creator | `~/.claude/skills/skill-creator/SKILL.md` | +| Plan commits as reviewable work units; commit splitting | work-unit-commits | `~/.claude/skills/work-unit-commits/SKILL.md` | +| Build distinctive, production-grade frontend interfaces | frontend-design | `~/.claude/plugins/cache/claude-plugins-official/frontend-design/e30768372b41/skills/frontend-design/SKILL.md` | +| Persistent memory — save decisions, conventions, bugs proactively | engram:memory | `~/.claude/plugins/cache/engram/engram/0.1.0/skills/memory/SKILL.md` | +| Opinionated constraints for building UIs with agents (Tailwind + motion/react + Base UI) | ui-skills | `~/.cursor/skills/ui-skills/SKILL.md` | + +## Built-in / harness-provided skills (no SKILL.md on disk) + +These appear in `` but are not invokable via filesystem scan. Invoke via the `Skill` tool with the exact slug. + +| Skill | Trigger | +|---|---| +| simplify | Review changed code for reuse, quality, efficiency; remove duplication / over-abstraction | +| rams | Accessibility and visual design review | +| web-interface-guidelines | Review UI code for Vercel Web Interface Guidelines compliance | +| review | Standard PR review workflow | +| security-review | Security review of pending branch changes | +| init | Initialize a CLAUDE.md file with codebase documentation | +| claude-api | Build / debug / optimize Claude API + Anthropic SDK apps; prompt caching | +| update-config | Configure Claude Code harness via settings.json — hooks, permissions, env vars | +| keybindings-help | Customize keyboard shortcuts in `~/.claude/keybindings.json` | +| fewer-permission-prompts | Add prioritized allowlist to project `.claude/settings.json` | +| loop | Run a prompt on a recurring interval or self-paced | +| schedule | Cron-scheduled remote agents | +| claudebeat:pick / claudebeat:settings | Configure notification sounds (not relevant to verbum dev) | + +--- + +## Compact Rules + +Pre-digested rules per skill. Delegators copy matching blocks into sub-agent prompts as `## Project Standards (auto-resolved)`. + +### agent-readability-inspector +- Resolve target FIRST: URL or local project — never both implicitly. +- URL targets: WebFetch the URL plus `/llms.txt`, `/robots.txt`, `/sitemap.xml` only. No deep crawl. +- Local targets: read files only — no `pnpm dev`, no network, no builds. +- Group findings by category — Discovery / Structure / Context. Never lump. +- Each finding: `PASS`/`WARN`/`FAIL` + evidence (path or URL fragment + 1-line quote) + one-sentence imperative fix. +- Report only. Do NOT auto-edit files. The user decides what to apply. + +### branch-pr +- Every PR MUST link an approved issue (`status:approved` label) — no exceptions. +- Every PR MUST have exactly one `type:*` label. +- Branch names MUST match `^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$`. +- Use conventional commits in PR commit messages. +- Run shellcheck on modified scripts before opening PR. +- Wait for automated checks to pass before merge. + +### chained-pr +- Split PRs over 400 changed lines unless maintainer accepts `size:exception`. +- Each PR reviewable in ≤60 minutes; one deliverable work unit per PR. +- Every chained PR states start, end, prior deps, follow-up, and out-of-scope. +- Every child PR includes a dependency diagram marking the current PR with the pin emoji. +- Feature Branch Chain: draft/no-merge tracker PR; child #1 targets tracker, later children target immediate parent. +- Polluted diff = base bug — retarget or rebase until only the current work unit appears. +- Do NOT mix chain strategies after the user chooses one. + +### cognitive-doc-design +- Lead with the answer — decision/action/outcome first, context after. +- Progressive disclosure: happy path first, then edges and references. +- Chunking: small grouped sections; flat lists stay short. +- Signposting: headings, callouts, summaries so readers know where they are. +- Recognition over recall: tables, checklists, examples, templates over remembered prose. +- Review empathy: design so reviewers can verify intent without reconstructing the story. + +### comment-writer +- Be useful fast — start with the actionable point, no PR recap. +- Warm and direct, not corporate-bot. +- 1–3 short paragraphs or a tight bullet list. Explain WHY when asking for a change. +- No pile-ons — comment on the highest-value issue, not every preference. +- Match thread language; in Spanish, use Rioplatense voseo (`podés`, `tenés`, `fijate`, `dale`). +- No em dashes. Use commas, periods, or parentheses. + +### explain-blockers +- One blocker = one H3 section. Never merge blockers into one paragraph. +- Each section follows the Four-Part Shape: What → Why it matters → The fork → My instinct (optional). +- ONE closing question at the very end — not per-blocker. +- Concepts before code — no code blocks; reference paths if load-bearing. +- Pro/Con MUST be a named consequence ("requires a migration later"), not vague adjectives ("more flexible"). +- Plain language is not baby talk. Don't condescend. -## Project Skills +### issue-creation +- Blank issues are disabled — MUST use a template (bug report or feature request). +- Every issue auto-gets `status:needs-review`; PR is blocked until maintainer adds `status:approved`. +- Search for duplicates BEFORE filing. +- Questions go to Discussions, not Issues. +- Fill ALL required template fields and tick pre-flight checkboxes. -(none — verbum has no project-level `.claude/skills/` configured yet) +### judgment-day +- Launch TWO blind judges in parallel with identical target and criteria. Never review the code yourself. +- Resolve project skills FIRST and inject the same `Project Standards` block into both judges and any fix prompts. +- Wait for BOTH judges before synthesis — never accept a partial verdict. +- `WARNING (real)` only if normal intended use can trigger it; otherwise downgrade to `WARNING (theoretical)`/INFO. +- Ask before fixing Round 1 confirmed issues. After any fix, immediately re-launch both judges before commit/push/done. +- Terminal states: `JUDGMENT: APPROVED` or `JUDGMENT: ESCALATED`. After 2 fix iterations, ask whether to continue. + +### repo-seo +- Three surfaces — GitHub (description + topics + README), package registry, Google/external. Hit all three or leave reach on the table. +- Description recipe: ` —
`. Max 350 chars, target ~120. +- GitHub topics: 12–18, lowercase, hyphen-separated; mix domain + form factor + stack + architecture + audience. +- Don't pad with `code`, `software`, `project`, `tool`, `awesome` — they don't rank. +- README header: ONE H1, subtitle as blockquote, 5–6 badges max, keyword-rich opening paragraph. +- Always propose first, apply on user approval — these are externally-visible changes. +- Don't restructure the README body — only the header — unless asked. + +### sharpen-scope +- Every question carries 2–3 concrete candidate answers grounded in project context. Never ask "what do you want?" raw. +- ONE question at a time, then STOP and wait. +- Name vagueness as vagueness — call out placeholders like "next step", "cleaner", "polish". +- Refuse to delegate to `sdd-explore` or downstream coding until the Four Sharps are answered concretely. +- The Four Sharps: Intent (problem in one sentence) → First Reviewable Cut (smallest end-to-end slice + what's OUT) → Success Criterion (one observable behavior) → Riskiest Unknown. + +### skill-creator +- A skill is a runtime instruction contract for an LLM, not human documentation. +- Frontmatter: `name`, `description` starts with `Trigger: . .`, license, metadata. +- Do NOT add a `Keywords` section — preserve trigger words in `description`. +- Body length: target 180–450 tokens, hard max 1000. Move overflow to `assets/` or `references/`. +- References point to LOCAL files only. +- If `docs/skill-style-guide.md` exists, apply it before fallback rules. + +### work-unit-commits +- Commit by deliverable behavior, fix, migration, or docs unit — NOT by file type. +- Tests ship with the behavior they verify, in the same commit. +- Docs ship with the user-visible change they explain. +- Each commit reviewable on its own; repo still makes sense after applying only that commit. +- Each commit a candidate chained PR if the change grows. +- If SDD forecasts >400 lines, group commits into chained-PR slices BEFORE implementation. + +### frontend-design +- Pick an extreme aesthetic and execute with precision (brutalist, editorial, organic, retro-futuristic, etc.) — NEVER generic "AI slop". +- Avoid Inter / Roboto / Arial / system fonts and purple-gradient-on-white. Pair a distinctive display font with a refined body font. +- Use CSS variables for color consistency. Dominant colors with sharp accents outperform timid even palettes. +- Animations: high-impact moments (staggered page load beats scattered micro-interactions). CSS-only for HTML; `motion/react` for React. +- Compose spatially: asymmetry, overlap, diagonal flow, controlled density or generous negative space. +- Match implementation complexity to the aesthetic — maximalism needs elaborate code; minimalism needs restraint. + +### engram:memory +- ALWAYS ACTIVE. Call `mem_save` IMMEDIATELY after: decisions, conventions, bug fixes, discoveries, gotchas, user confirmations/rejections, preferences. +- `mem_save` content shape: **What** (one sentence) + **Why** (motivation) + **Where** (paths) + **Learned** (gotchas). +- Topic key for evolving topics: stable key like `architecture/auth-model`. Same topic → same key (upsert). +- `capture_prompt: false` ONLY for automated artifacts (SDD phases, registry, init reports). Default true for human/proactive saves. +- Search before assuming context: `mem_context` for recent sessions, `mem_search` for keywords, `mem_get_observation` for full content. +- Before saying "done"/"listo": call `mem_session_summary` with Goal / Discoveries / Accomplished / Next Steps / Relevant Files. + +### ui-skills +- Tailwind CSS defaults unless custom exists or is explicitly requested. +- `motion/react` for JS animation; `tw-animate-css` for entrances and micro-animations; `cn` (clsx + tailwind-merge) for class logic. +- MUST use accessible primitives (Base UI / React Aria / Radix) — never rebuild keyboard/focus behavior by hand. +- NEVER mix primitive systems within one interaction surface. +- `aria-label` on icon-only buttons. `AlertDialog` for destructive/irreversible actions. Errors next to the action. +- `h-dvh` not `h-screen`. Respect `safe-area-inset` for fixed elements. +- Animation: only `transform` and `opacity`; never layout (`width/height/top/left/margin/padding`); ≤200ms for interaction feedback; respect `prefers-reduced-motion`. +- NEVER add animation unless explicitly requested. + +--- ## Project Conventions -| Source | Path | Relevance | +| File | Path | Notes | |---|---|---| -| User CLAUDE.md | `/Users/ivanmaierg/.claude/CLAUDE.md` | Applies to all projects — voseo Spanish, no AI commit attribution, pnpm preference (overridden for verbum: Bun is required by OpenTUI), brevity contract, response patterns | -| Project CLAUDE.md | `(none yet)` | Could be added at `/Users/ivanmaierg/Desktop/misc/verbum/CLAUDE.md` if project-specific instructions emerge | -| House rules | `docs/house-rules.md` | **The 12 enforceable code-review rules** — cite by number in PR comments. Designed for Go-port readiness. | - -## Compact Rules — Skills Most Likely Relevant to verbum - -When delegating to sub-agents that touch verbum source code or docs, prefer these compact rule sets: - -### From `docs/house-rules.md` (highest priority) -- **R1**: Domain functions never throw — return `Result` -- **R2**: No `class` outside `src/tui/` React components -- **R3**: Ports = interfaces with primitive/struct args, no callbacks -- **R4**: Zod stays in `src/api/` — domain imports plain TS types -- **R5**: Errors are discriminated unions with `kind` field -- **R6**: Branded IDs via single factory; no `as BookId` casts elsewhere -- **R7**: No conditional/mapped/template-literal types in domain or application -- **R8**: TUI business state in `useReducer`; `useState` for ephemeral UI only -- **R9**: No `useEffect` for business logic — Effect descriptors via top-level runner -- **R10**: Action names are past-tense facts (`ChapterLoaded`, `KeyPressed`) -- **R11**: No decorators — explicit higher-order functions -- **R12**: Async data functions return `Promise>`, never bare `Promise` - -### From `cognitive-doc-design` -- Lead with the decision, not the context -- Progressive disclosure: happy path first, edge cases after -- Tables and checklists over prose - -### From `simplify` -- Reuse existing utilities before creating new ones -- Question every new abstraction -- Three similar lines is fine; the abstraction is premature - -### From `work-unit-commits` -- Each commit reviewable on its own -- Tests + docs ship with the code that motivated them -- No "WIP" or "fix typo from X" commits in a clean history +| User CLAUDE.md | `/Users/ivanmaierg/.claude/CLAUDE.md` | Applies to all projects — Rioplatense Spanish (voseo), no AI commit attribution, RTK tool usage, brevity contract, one-question-at-a-time, no `cat`/`grep`/`find`/`sed`/`ls` (use `bat`/`rg`/`fd`/`sd`/`eza`) | +| RTK | `/Users/ivanmaierg/.claude/RTK.md` | Rust Token Killer — token-optimized CLI proxy; auto-rewrites commands via Claude Code hook | +| House Rules | `/Users/ivanmaierg/Desktop/misc/verbum/docs/house-rules.md` | **12 enforceable code-review rules** — cite by number. Designed for Go-port readiness. | + +### Compact Rules — House Rules (R1–R12) + +Highest-priority project constraints. Inject into ANY sub-agent that touches `src/` or `tests/`. + +- **R1**: Domain functions never throw — return `Result`. Throwing in `src/domain/` is a review-blocker. +- **R2**: No `class` outside React components in `src/tui/`. Use cases, parsers, repos, value objects, adapters are functions or plain object factories. +- **R3**: Ports = interfaces with primitive/struct args, no callbacks. No event emitters, observables, or streaming via callbacks. +- **R4**: Zod stays in `src/api/` — domain imports plain TS types. Validation lives at the boundary. +- **R5**: Errors are discriminated unions with `kind` field. Exhaustive renderers per error variant. +- **R6**: Branded IDs via a single factory; no `as BookId` casts elsewhere. +- **R7**: No conditional/mapped/template-literal types in domain or application. Keep types Go-portable. +- **R8**: TUI business state in `useReducer`; `useState` for ephemeral UI only. +- **R9**: No `useEffect` for business logic — Effect descriptors via top-level runner. +- **R10**: Action names are past-tense facts (`ChapterLoaded`, `KeyPressed`, `VerseRequested`). +- **R11**: No decorators — explicit higher-order functions only. +- **R12**: Async data functions return `Promise>`, never bare `Promise`. + +### Compact Rules — User CLAUDE.md (verbum-relevant excerpts) + +- Default to short answers. Start with minimum useful response, expand only when asked. +- ONE question at a time. After asking, STOP and wait. +- No option menus / exhaustive lists unless there's a real fork with meaningful tradeoffs. +- Never agree with user claims without verification. Verify, then state. +- If user is wrong: explain WHY with evidence; show the correct way. +- Use voseo Spanish (`podés`, `tenés`, `dale`) when conversing in Spanish; warm natural English otherwise. +- Never add `Co-Authored-By` or AI attribution to commits. Conventional commits only. +- Never build after changes (no `bun build`). +- Tools: prefer `bat`/`rg`/`fd`/`sd`/`eza` over `cat`/`grep`/`find`/`sed`/`ls`. +- Verbum-specific: English is the preferred conversation language for this project (per 2026-05-11 confirmation). + +--- + +## Notes for sub-agents + +- Receive these compact rules pre-digested in your launch prompt as `## Project Standards (auto-resolved)`. +- Do NOT read this registry yourself. +- Cite house rules by number (R1–R12) in any code review or implementation rationale. +- For verbum, `go-testing` is irrelevant — TypeScript / Bun project, no Go code. diff --git a/.gitignore b/.gitignore index 1aee701..b3285b8 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,6 @@ bun.lockb npm-debug.log* yarn-debug.log* yarn-error.log* + +# Agent Teams Lite — local skill registry and ephemeral state +.atl/