From fb1500087782442b53b4c55fd5bed5f9051315bc Mon Sep 17 00:00:00 2001 From: dan Date: Fri, 26 Dec 2025 01:18:19 -0500 Subject: [PATCH] refactor: restructure for cross-repo deployment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename reviews/ to lenses/ (clearer terminology) - Add workflows/ for beads proto templates - Extract code-review proto to workflows/molecules.jsonl - Update ai-skills.nix module: - Add enableLenses option (deploys to ~/.config/lenses/) - Add enableWorkflows option (deploys to ~/.beads/molecules.jsonl) - Derive repoRoot from skillsPath for sibling directories - Update lens paths in proto to use deployed location 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .beads/issues.jsonl | 12 +++++++++ {reviews => lenses}/README.md | 10 +++---- {reviews => lenses}/bloat.md | 0 {reviews => lenses}/dead-code.md | 0 {reviews => lenses}/redundancy.md | 0 {reviews => lenses}/smells.md | 0 modules/ai-skills.nix | 32 ++++++++++++++++++++++ workflows/README.md | 45 +++++++++++++++++++++++++++++++ workflows/molecules.jsonl | 7 +++++ 9 files changed, 101 insertions(+), 5 deletions(-) rename {reviews => lenses}/README.md (78%) rename {reviews => lenses}/bloat.md (100%) rename {reviews => lenses}/dead-code.md (100%) rename {reviews => lenses}/redundancy.md (100%) rename {reviews => lenses}/smells.md (100%) create mode 100644 workflows/README.md create mode 100644 workflows/molecules.jsonl diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 24f9aae..6732b62 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -52,6 +52,13 @@ {"id":"skills-ebl","title":"Benchmark vision model UI understanding","description":"## Goal\nMeasure how well vision models can answer UI questions from screenshots.\n\n## Test cases\n1. **Element location**: \"Where is the Save button?\" → coordinates\n2. **Element identification**: \"What buttons are visible?\" → list\n3. **State detection**: \"Is the checkbox checked?\" → boolean\n4. **Text extraction**: \"What does the error message say?\" → text\n5. **Layout understanding**: \"What's in the sidebar?\" → structure\n\n## Metrics\n- Accuracy: Does the answer match ground truth?\n- Precision: How close are coordinates to actual element centers?\n- Latency: Time from query to response\n- Cost: Tokens consumed per query\n\n## Prompt engineering questions\n- Does adding a grid overlay help coordinate precision?\n- What prompt format gives most actionable coordinates?\n- Can we get bounding boxes vs point coordinates?\n\n## Comparison baseline\n- Manual annotation of test screenshots\n- AT-SPI data (once enabled) as ground truth\n\n## Depends on\n- Test screenshots from real apps\n- Ground truth annotations","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T14:13:10.038933798-08:00","updated_at":"2025-12-17T14:13:10.038933798-08:00"} {"id":"skills-f2p","title":"Skills + Molecules Integration","description":"Integrate skills with beads molecules system.\n\nDesign work tracked in dotfiles (dotfiles-jjb).\n\nComponents:\n- Checklist support (lightweight skills)\n- Audit integration (bd audit for skill execution)\n- Skill frontmatter for triggers/tracking\n- Proto packaging alongside skills\n\nSee: ~/proj/dotfiles ADR work","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-23T17:58:55.999438985-05:00","updated_at":"2025-12-23T19:22:38.577280129-05:00","closed_at":"2025-12-23T19:22:38.577280129-05:00","close_reason":"Superseded by skills-4u0 (migrated from dotfiles)","dependencies":[{"issue_id":"skills-f2p","depends_on_id":"skills-vpy","type":"blocks","created_at":"2025-12-23T17:59:17.976956454-05:00","created_by":"daemon"},{"issue_id":"skills-f2p","depends_on_id":"skills-u3d","type":"blocks","created_at":"2025-12-23T17:59:18.015216054-05:00","created_by":"daemon"}]} {"id":"skills-fo3","title":"Compare WORKFLOWS.md with upstream","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.283175561-08:00","updated_at":"2025-12-03T20:19:28.897037199-08:00","closed_at":"2025-12-03T20:19:28.897037199-08:00","dependencies":[{"issue_id":"skills-fo3","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.286009672-08:00","created_by":"daemon","metadata":"{}"}]} +{"id":"skills-fvc","title":"Code Review: {{target}}","description":"Multi-lens code review workflow for {{target}}.\n\n## Variables\n- target: File or directory to review\n\n## Workflow\n1. Run each lens via orch consensus (flash + gemini)\n2. Analyze findings\n3. File actionable items as beads\n4. Summarize findings in digest\n\n## Lenses\n- bloat: size, complexity, SRP violations\n- smells: readability, naming, control flow\n- dead-code: unused, unreachable, obsolete\n- redundancy: duplication, YAGNI, parallel systems","status":"open","priority":2,"issue_type":"epic","created_at":"2025-12-25T10:10:57.652098447-05:00","updated_at":"2025-12-25T10:10:57.652098447-05:00","labels":["template"]} +{"id":"skills-fvc.1","title":"Run bloat lens on {{target}}","description":"Run bloat review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/bloat.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: file size, function length, complexity, SRP violations.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:13:59.789715667-05:00","updated_at":"2025-12-26T01:15:59.453348311-05:00","dependencies":[{"issue_id":"skills-fvc.1","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:13:59.80248308-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.2","title":"Run smells lens on {{target}}","description":"Run smells review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/smells.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: naming issues, control flow smells, data smells, structural issues.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:13.977562568-05:00","updated_at":"2025-12-26T01:16:43.064403777-05:00","dependencies":[{"issue_id":"skills-fvc.2","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:13.989662453-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.3","title":"Run dead-code lens on {{target}}","description":"Run dead-code review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/dead-code.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: zombie code, unreachable paths, obsolete shims, import cruft.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:17.522715411-05:00","updated_at":"2025-12-26T01:16:48.452520859-05:00","dependencies":[{"issue_id":"skills-fvc.3","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:17.53423496-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.4","title":"Run redundancy lens on {{target}}","description":"Run redundancy review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/redundancy.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: duplication, parallel systems, YAGNI violations, consolidation opportunities.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:21.94274481-05:00","updated_at":"2025-12-26T01:16:52.579297412-05:00","dependencies":[{"issue_id":"skills-fvc.4","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:21.956965459-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.5","title":"File findings as beads","description":"Review all lens findings and file actionable items as beads:\n\nFor each HIGH/MED severity finding:\n```bash\nbd create --title=\"{{target}}: \u003cissue\u003e\" --type=task --priority=3 --body=\"Found by \u003clens\u003e lens review. \u003cdetails\u003e\"\n```\n\nGroup related findings. Skip LOW severity unless pattern emerges.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:34.288221353-05:00","updated_at":"2025-12-25T10:16:34.288221353-05:00","dependencies":[{"issue_id":"skills-fvc.5","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:34.303313556-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.6","title":"Summarize review findings","description":"Create summary of code review findings for {{target}}:\n\n- Total findings by severity (HIGH/MED/LOW)\n- Top issues by category\n- Recommendations for immediate action\n- Technical debt assessment\n\nThis summary will become the squash digest.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:34.590409022-05:00","updated_at":"2025-12-25T10:16:34.590409022-05:00","dependencies":[{"issue_id":"skills-fvc.6","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:34.591813242-05:00","created_by":"daemon"}]} {"id":"skills-fvx","title":"use-skills.sh: stderr from nix build corrupts symlinks when repo is dirty","description":"In use-skills.sh, the line:\n\n```bash\nout=$(nix build --print-out-paths --no-link \"${SKILLS_REPO}#${skill}\" 2\u003e\u00261) || {\n```\n\nThe `2\u003e\u00261` merges stderr into stdout. When the skills repo is dirty, nix emits a warning to stderr which gets captured into $out and used as the symlink target.\n\nResult: symlinks like:\n```\norch -\u003e warning: Git tree '/home/dan/proj/skills' is dirty\n/nix/store/j952hgxixifscafb42vmw9vgdphi1djs-ai-skill-orch\n```\n\nFix: redirect stderr to /dev/null or filter it out before creating symlink.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-14T11:54:03.06502295-08:00","updated_at":"2025-12-14T11:59:25.472044754-08:00","closed_at":"2025-12-14T11:59:25.472044754-08:00"} {"id":"skills-gas","title":"spec-review: File discovery is brittle, can pick wrong file silently","description":"The fallback `find ... | head -1` is non-deterministic and can select wrong spec/plan/tasks file without user noticing. Branch names with `/` also break path construction.\n\nFixes:\n- Fail fast if expected file missing\n- Print chosen file path before proceeding\n- Require explicit confirmation if falling back\n- Handle branch names with slashes","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-15T00:23:22.762045913-08:00","updated_at":"2025-12-15T00:46:16.231199231-08:00","closed_at":"2025-12-15T00:46:16.231199231-08:00"} {"id":"skills-gga","title":"Configure Claude Code LSP integration","description":"Claude Code now has LSP (Language Server Protocol) integration that provides semantic code understanding.\n\n## Key Features\n- Go to Definition - Jump to symbol declarations\n- Find References - Locate all usages (safe refactoring) \n- Hover/Type Info - Get signatures, docstrings, types\n- Diagnostics - See compiler errors/warnings directly\n\n## Setup Required\n1. Enable via env var: ENABLE_LSP_TOOL=1\n2. Install language servers on PATH:\n - TypeScript: typescript-language-server\n - Python: pyright or python-lsp-server\n - Go: gopls\n - Rust: rust-analyzer\n - Nix: nil or nixd\n\n3. Optional: MCP adapter like cclsp for robust AI→LSP bridging\n\n## Tasks\n- [ ] Add language servers to Nix packages\n- [ ] Set ENABLE_LSP_TOOL=1 in shell environment\n- [ ] Test with representative projects\n- [ ] Consider creating an LSP skill documenting available servers\n\n## References\n- Discovered via orch consensus with sonar, flash-or, glm\n- Related to skills+molecules integration (semantic code understanding for traces)","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-24T02:16:40.510669749-05:00","updated_at":"2025-12-24T23:33:58.635002347-05:00","closed_at":"2025-12-24T23:33:58.635002347-05:00","close_reason":"LSP servers deployed (gopls, pyright, typescript-language-server, rust-analyzer, nil, elixir-ls); ENABLE_LSP_TOOL=1 in sessionVariables; requires new session to test"} @@ -62,6 +69,7 @@ {"id":"skills-hh2","title":"skill: rename_symbol with LSP + validation","description":"Skill that performs safe renames:\n1. Uses LSP textDocument/rename\n2. Runs formatters\n3. Checks LSP diagnostics post-rename\n4. Opens bead if errors remain\n5. Updates doc references using hover/signatureHelp\n\nInput: new name, scope. Output: clean rename or bead with issues.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-24T02:29:56.87156069-05:00","updated_at":"2025-12-24T02:29:56.87156069-05:00","dependencies":[{"issue_id":"skills-hh2","depends_on_id":"skills-gga","type":"blocks","created_at":"2025-12-24T02:30:06.583813579-05:00","created_by":"daemon"}]} {"id":"skills-hin","title":"ADR: Skills and Molecules Integration Design","description":"Write Architecture Decision Record documenting:\n- Current state (skills via Nix/direnv, molecules via beads)\n- Decision to link via skill: references\n- Wisp trace format spec\n- Elevation pipeline design\n- Anti-patterns to avoid\n\nLocation: docs/adr/001-skills-molecules-integration.md\n\nMigrated from dotfiles-dn8 (was in_progress).\n\n## Current State\n- ADR-001 drafted (high-level integration)\n- ADR-002, 003, 004 drafted and revised (manifest, versioning, security)\n- Orch consensus feedback incorporated\n\n## Parked\nDeferring finalization until we see Steve Yegge's new orchestration work and how it might inform our design.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-23T19:20:47.568903148-05:00","updated_at":"2025-12-24T02:41:40.676399328-05:00"} {"id":"skills-idb","title":"Handle concurrency and multi-agent execution","description":"Not addressed in ADR. Questions:\n\n- What happens when two agents run same skill on same mol step?\n- How to handle partial failures and resumptions?\n- Trace merging: append-only log vs latest-wins?\n\nNeeds:\n- execution_id and parent_execution_id in traces\n- Step completion idempotency declaration\n- Define how multiple traces attach to one mol node\n\nCan defer until basic integration works.","status":"open","priority":4,"issue_type":"task","created_at":"2025-12-23T19:49:59.608603168-05:00","updated_at":"2025-12-23T19:49:59.608603168-05:00"} +{"id":"skills-j2a","title":"worklog: consolidate git commands into extract-metrics.sh","description":"Context Gathering section has raw git commands, but extract-metrics.sh also exists. Feature envy - split logic. Move all git context gathering into the script, skill makes single call. Found by smells lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.478103649-05:00","updated_at":"2025-12-25T02:03:16.478103649-05:00"} {"id":"skills-jbo","title":"Skills: verify symbols via LSP before suggesting","description":"Inversion: let LSP answer facts, let models answer strategy.\n\nBefore Claude suggests using a function/type:\n- Verify existence via workspace/symbol or go-to-definition\n- If not found, propose alternatives that ARE found\n- Gather definition, references, inferred types, diagnostics as context\n\nReduces hallucinated APIs and grounds patches in reality.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-24T02:29:56.391182872-05:00","updated_at":"2025-12-24T02:29:56.391182872-05:00","dependencies":[{"issue_id":"skills-jbo","depends_on_id":"skills-gga","type":"blocks","created_at":"2025-12-24T02:30:06.529604354-05:00","created_by":"daemon"}]} {"id":"skills-jeb","title":"Define wisp execution trace format","description":"Design structured format for skill execution traces in wisps:\n- skill_version (git SHA + flake hash)\n- inputs (context refs, env vars)\n- tool_calls [{cmd, args, exit_code, duration}]\n- checkpoints [{step, summary, timestamp}]\n- outputs (file diffs or refs)\n\nEnable: replay, diff traces, regression testing\n\nMigrated from dotfiles-ub9.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-23T19:20:57.896088397-05:00","updated_at":"2025-12-23T19:20:57.896088397-05:00","dependencies":[{"issue_id":"skills-jeb","depends_on_id":"skills-hin","type":"blocks","created_at":"2025-12-23T19:21:39.588011474-05:00","created_by":"dan"},{"issue_id":"skills-jeb","depends_on_id":"skills-gq9","type":"blocks","created_at":"2025-12-23T19:50:10.069841366-05:00","created_by":"daemon"},{"issue_id":"skills-jeb","depends_on_id":"skills-be3","type":"blocks","created_at":"2025-12-23T19:50:10.117400312-05:00","created_by":"daemon"},{"issue_id":"skills-jeb","depends_on_id":"skills-ty7","type":"blocks","created_at":"2025-12-23T19:50:10.163656807-05:00","created_by":"daemon"},{"issue_id":"skills-jeb","depends_on_id":"skills-6gw","type":"blocks","created_at":"2025-12-23T19:50:10.202702536-05:00","created_by":"daemon"}]} {"id":"skills-kg7","title":"Desktop automation for Wayland/niri","description":"Explore and implement desktop automation solutions for Wayland (niri compositor).\n\n## The Seeing Problem\n\nHow can an AI agent understand what's on screen?\n\n### Layers (bottom to top)\n1. **Window awareness** - what's open, app_id, title → niri IPC ✅\n2. **Window geometry** - size, position, monitor → niri IPC ✅\n3. **Pixel capture** - screenshots → niri screenshot-window ✅\n4. **Understanding** - UI elements, coordinates, semantics → **GAP**\n\n### Two paths to understanding (layer 4)\n\n**Path A: AT-SPI (structured)**\n- Pros: precise coordinates, semantic element types, states\n- Cons: runtime overhead, requires NixOS config, app compliance varies\n- Coverage: GTK ✅, Qt (with env var), Electron ❓\n\n**Path B: Vision model (visual)**\n- Pros: universal (works on any pixels), no system config needed\n- Cons: API latency, token cost, coordinate precision unclear\n- Coverage: anything visible ✅\n\n### Hybrid approach\nRun both, benchmark tradeoffs:\n- AT-SPI overhead vs query precision\n- Vision model latency/cost vs coverage\n- When to use which (or both for validation)\n\n## What we have\n- niri-window-capture skill (screenshots, window list)\n- niri IPC for window/monitor geometry\n\n## Context\nWayland's security model blocks X11-style automation. Solutions require:\n- Compositor-specific IPC (niri msg)\n- App opt-in via AT-SPI accessibility\n- Or vision model interpretation of pixels","status":"open","priority":2,"issue_type":"epic","created_at":"2025-12-17T12:42:17.863074501-08:00","updated_at":"2025-12-17T14:12:59.143207802-08:00","dependencies":[{"issue_id":"skills-kg7","depends_on_id":"skills-pdg","type":"blocks","created_at":"2025-12-17T13:59:59.915105471-08:00","created_by":"daemon","metadata":"{}"},{"issue_id":"skills-kg7","depends_on_id":"skills-ebl","type":"blocks","created_at":"2025-12-17T14:13:41.679692009-08:00","created_by":"daemon","metadata":"{}"},{"issue_id":"skills-kg7","depends_on_id":"skills-bww","type":"blocks","created_at":"2025-12-17T14:13:41.725196677-08:00","created_by":"daemon","metadata":"{}"}]} @@ -72,10 +80,12 @@ {"id":"skills-lzk","title":"Simplify branch name generation in create-new-feature.sh","description":"File: .specify/scripts/bash/create-new-feature.sh (lines 137-181)\n\nIssues:\n- 3 nested loops/conditionals\n- Complex string transformations with multiple sed operations\n- Stop-words list and filtering logic hard to maintain\n\nFix:\n- Extract to separate function\n- Simplify word filtering logic\n- Add input validation\n\nSeverity: MEDIUM","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-24T02:51:14.286951249-05:00","updated_at":"2025-12-24T02:51:14.286951249-05:00"} {"id":"skills-m21","title":"Apply niri-window-capture code review recommendations","description":"CODE-REVIEW-niri-window-capture.md identifies action items: add dependency checks to scripts, improve error handling for niri failures, add screenshot directory validation, implement rate limiting. See High/Medium priority sections.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.648846875-08:00","updated_at":"2025-11-30T11:58:24.648846875-08:00"} {"id":"skills-mx3","title":"spec-review: Define consensus thresholds and decision rules","description":"'Use judgment' for mixed results leads to inconsistent decisions.\n\nDefine:\n- What constitutes consensus (2/3? unanimous?)\n- How to handle NEUTRAL votes\n- Tie-break rules\n- When human override is acceptable and how to document it","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-15T00:23:24.121175736-08:00","updated_at":"2025-12-15T13:58:04.339283238-08:00","closed_at":"2025-12-15T13:58:04.339283238-08:00"} +{"id":"skills-njb","title":"worklog: clarify or remove semantic compression references","description":"SKILL.md references 'semantic compression is a planned workflow' multiple times but it's not implemented. Speculative generality - adds cognitive load for non-existent feature. Either implement or move to design notes. Found by smells lens review.","status":"open","priority":4,"issue_type":"task","created_at":"2025-12-25T02:03:25.387405002-05:00","updated_at":"2025-12-25T02:03:25.387405002-05:00"} {"id":"skills-oes","title":"Define skill manifest format","description":"Skills need to declare their interface so beads can validate.\n\nManifest should include:\n- Required inputs (args, env vars)\n- Optional inputs with defaults\n- Expected outputs (files, artifacts)\n- Preconditions (tools, repos, permissions)\n\nLocation: SKILL.md frontmatter or separate manifest.yaml\n\nEnables: Proto validation before spawning, better error messages.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T19:49:30.673372413-05:00","updated_at":"2025-12-23T20:55:04.427620449-05:00","closed_at":"2025-12-23T20:55:04.427620449-05:00","close_reason":"ADRs revised with orch consensus feedback"} {"id":"skills-p2o","title":"Refactor update-agent-context.sh: array+loop for agents","description":"File: .specify/scripts/bash/update-agent-context.sh (772 lines)\n\nIssues:\n- 12 nearly-identical if-blocks in update_all_existing_agents() (lines 632-701)\n- Should be refactored into loop with array of agent configurations\n- Current pattern repeats: if [[ -f \"$CLAUDE_FILE\" ]]; then update_agent_file...\n\nFix:\n- Create AGENTS array with (file, name, format) tuples\n- Replace 12 if-blocks with single for loop\n- Estimated reduction: 60 lines\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.385820971-05:00","updated_at":"2025-12-25T01:44:58.370191619-05:00","closed_at":"2025-12-25T01:44:58.370191619-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"} {"id":"skills-p3v","title":"Cross-language FFI wormholes via LSP","description":"Bridge FFI boundaries where standard LSPs go blind:\n- Rust extern C → clangd lookup\n- Go CGO → match C symbols\n- Python FFI → trace bindings\n\nGenerate synthetic go-to-definition maps. When hovering over C call in Rust, intercept hover request, query C LSP, inject C definition into Rust tooltip.\n\nEnables seamless polyglot navigation.","status":"open","priority":4,"issue_type":"feature","created_at":"2025-12-24T02:29:57.597602745-05:00","updated_at":"2025-12-24T02:29:57.597602745-05:00"} {"id":"skills-pdg","title":"Enable AT-SPI for UI tree access","description":"## Findings\n\nAT-SPI (Assistive Technology Service Provider Interface) provides semantic UI tree access - buttons, labels, text fields, their states and coordinates.\n\n### Current state\n- AT-SPI is **disabled** on this NixOS system\n- Environment has `NO_AT_BRIDGE=1` and `GTK_A11Y=none`\n- No apps are exposing accessibility info\n\n### To enable\n```nix\nservices.gnome.at-spi2-core.enable = true;\n```\n\nThen rebuild and re-login (apps must start fresh to register with bus).\n\n### App support\n- **GTK apps**: Should work automatically\n- **Qt apps**: Need `QT_LINUX_ACCESSIBILITY_ALWAYS_ON=1` env var\n- **Electron**: Varies by app, often poor support\n\n### Trade-offs\n- Adds runtime overhead to all GTK/Qt apps\n- May want as boot-time option rather than always-on\n- Only useful for automation/accessibility use cases\n\n### Tools once enabled\n- `python3-pyatspi` / `dogtail` for querying UI tree\n- `accerciser` for visual inspection of accessibility tree\n\n### Next steps\n1. Add NixOS option (possibly as boot-time toggle)\n2. Test with common apps (Firefox, terminals, etc.)\n3. Build skill to query UI elements\n\n## Related\nParent epic: skills-kg7 (Desktop automation for Wayland/niri)","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-17T13:59:55.799402507-08:00","updated_at":"2025-12-17T13:59:55.799402507-08:00"} +{"id":"skills-prt","title":"worklog: remove inline section list, reference template","description":"SKILL.md lists 11 sections that duplicate worklog-template.org. Will drift. Replace with directive to parse sections from template dynamically. Found by bloat lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.811093872-05:00","updated_at":"2025-12-25T02:03:16.811093872-05:00"} {"id":"skills-pu4","title":"Clean up stale beads.left.jsonl merge artifact","description":"bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.292221449-08:00","updated_at":"2025-11-30T12:37:49.916795223-08:00","closed_at":"2025-11-30T12:37:49.916795223-08:00"} {"id":"skills-qeh","title":"Add README.md for web-research skill","description":"web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.475647113-08:00","updated_at":"2025-11-30T12:00:30.309340468-08:00","dependencies":[{"issue_id":"skills-qeh","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.278784381-08:00","created_by":"daemon","metadata":"{}"}]} {"id":"skills-r5c","title":"Extract shared logging library from scripts","description":"Duplicated logging/color functions across multiple scripts:\n- bin/deploy-skill.sh\n- skills/tufte-press/scripts/generate-and-build.sh\n- Other .specify scripts\n\nPattern repeated:\n- info(), warn(), error() functions\n- Color definitions (RED, GREEN, etc.)\n- Same 15-20 lines in each file\n\nFix:\n- Create scripts/common-logging.sh\n- Source from all scripts that need it\n- Estimated reduction: 30+ lines of duplication\n\nSeverity: MEDIUM","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:58.324852578-05:00","updated_at":"2025-12-24T02:50:58.324852578-05:00"} @@ -84,6 +94,7 @@ {"id":"skills-s92","title":"Add tests for config injection (deploy-skill.sh)","description":"File: bin/deploy-skill.sh (lines 112-137)\n\nCritical logic with NO test coverage:\n- Idempotency (running twice should be safe)\n- Correct brace matching in Nix\n- Syntax validity of injected config\n- Rollback on failure\n\nRisk: MEDIUM-HIGH - can break dotfiles Nix config\n\nFix:\n- Test idempotent injection\n- Validate Nix syntax after injection\n- Test with malformed input\n\nSeverity: MEDIUM","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-24T02:51:01.314513824-05:00","updated_at":"2025-12-24T02:51:01.314513824-05:00"} {"id":"skills-ty7","title":"Define trace levels (audit vs debug)","description":"Two trace levels to manage noise vs utility:\n\n1. Audit trace (minimal, safe, always on):\n - skill id/ref, start/end\n - high-level checkpoints\n - artifact hashes/paths\n - exit status\n\n2. Debug trace (opt-in, verbose):\n - tool calls with args\n - stdout/stderr snippets\n - expanded inputs\n - timing details\n\nConsider OpenTelemetry span model as reference.\nGPT proposed this; Gemini focused on rotation/caps instead.","status":"in_progress","priority":3,"issue_type":"task","created_at":"2025-12-23T19:49:48.514684945-05:00","updated_at":"2025-12-23T20:05:23.244193346-05:00"} {"id":"skills-u3d","title":"Define skill trigger conditions","description":"How does an agent know WHEN to apply a skill/checklist?\n\nOptions:\n- frontmatter triggers: field with patterns\n- File-based detection\n- Agent judgment from description\n- Beads hooks on state transitions\n- LLM-based pattern detection","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-23T17:59:09.69468767-05:00","updated_at":"2025-12-23T17:59:09.69468767-05:00"} +{"id":"skills-uan","title":"worklog: merge Guidelines and Remember sections","description":"Guidelines (8 points) and Remember (6 points) sections overlap significantly - both emphasize comprehensiveness, future context, semantic compression. Consolidate into single principles list. Found by bloat lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:16.148596791-05:00","updated_at":"2025-12-25T02:03:16.148596791-05:00"} {"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon","metadata":"{}"}]} {"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"} {"id":"skills-vjm","title":"Refactor update-agent-context.sh: reduce nesting depth","description":"File: .specify/scripts/bash/update-agent-context.sh\n\nIssues:\n- update_existing_agent_file() has 4-level deep nesting (lines 360-499)\n- State machine with multiple variables: in_tech_section, in_changes_section, tech_entries_added\n- 70+ lines of while loop processing\n\nFix:\n- Extract file processing to separate function\n- Consider sed/awk for line-based transformations\n- Use guard clauses to reduce nesting\n\nSeverity: HIGH","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:50:57.874439288-05:00","updated_at":"2025-12-25T01:44:58.38265672-05:00","closed_at":"2025-12-25T01:44:58.38265672-05:00","close_reason":"update-agent-context.sh is .specify upstream code, not maintained here"} @@ -91,3 +102,4 @@ {"id":"skills-wm9","title":"Research Steve Yegge's orchestration work","description":"Steve Yegge is working on something new related to AI orchestration. Research what it is and how it might inform our skills+molecules integration design.\n\nBlocks: skills-hin (ADR finalization)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-24T02:41:47.848905848-05:00","updated_at":"2025-12-24T02:42:24.40239935-05:00","closed_at":"2025-12-24T02:42:24.40239935-05:00","close_reason":"Not needed - just parking the ADR work"} {"id":"skills-x2l","title":"Investigate hooks for parallel orch queries","description":"When using orch skill, it would be useful to spin off multiple model queries in parallel automatically (e.g., gemini + gpt simultaneously). Explore if Claude Code hooks can trigger parallel background processes when the orch skill is invoked.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-06T19:29:00.165752425-08:00","updated_at":"2025-12-06T19:29:00.165752425-08:00"} {"id":"skills-x33","title":"Add tests for branch name generation","description":"File: .specify/scripts/bash/create-new-feature.sh (lines 137-181)\n\nCritical logic with NO test coverage:\n- Word filtering with stop-words\n- Acronym detection\n- Unicode/special character handling\n- Max length boundary (244 bytes)\n- Empty/single-word descriptions\n\nRisk: HIGH - affects all branch creation\n\nFix:\n- Create test suite with edge cases\n- Test stop-word filtering accuracy\n- Test boundary conditions\n\nSeverity: HIGH","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-24T02:51:00.311664646-05:00","updated_at":"2025-12-24T02:51:00.311664646-05:00"} +{"id":"skills-yxv","title":"worklog: extract hardcoded path to variable","description":"SKILL.md repeats ~/.claude/skills/worklog/ path 4-5 times. Define SKILL_ROOT once, reference throughout. Found by bloat+smells lens review.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-25T02:03:15.831699081-05:00","updated_at":"2025-12-25T02:03:15.831699081-05:00"} diff --git a/reviews/README.md b/lenses/README.md similarity index 78% rename from reviews/README.md rename to lenses/README.md index 4579356..8595da2 100644 --- a/reviews/README.md +++ b/lenses/README.md @@ -1,6 +1,6 @@ -# Review Lenses +# Lenses -Focused review prompts for multi-perspective code analysis. +Focused prompts for multi-perspective code analysis. ## Philosophy @@ -10,19 +10,19 @@ Each lens examines code through one specific concern. Multiply lenses × models **Single lens, multiple models:** ```bash -orch consensus "$(cat reviews/bloat.md)" flash gemini gpt --file src/target.py +orch consensus "$(cat ~/.config/lenses/bloat.md)" flash gemini gpt --file src/target.py ``` **Pipe file content:** ```bash -cat src/target.py | orch consensus "$(cat reviews/smells.md)" flash gemini +cat src/target.py | orch consensus "$(cat ~/.config/lenses/smells.md)" flash gemini ``` **Convergent review (multiple passes):** ```bash for lens in bloat smells dead-code; do echo "=== $lens ===" - orch chat "$(cat reviews/$lens.md)" --model gemini --file src/target.py + orch chat "$(cat ~/.config/lenses/$lens.md)" --model gemini --file src/target.py done ``` diff --git a/reviews/bloat.md b/lenses/bloat.md similarity index 100% rename from reviews/bloat.md rename to lenses/bloat.md diff --git a/reviews/dead-code.md b/lenses/dead-code.md similarity index 100% rename from reviews/dead-code.md rename to lenses/dead-code.md diff --git a/reviews/redundancy.md b/lenses/redundancy.md similarity index 100% rename from reviews/redundancy.md rename to lenses/redundancy.md diff --git a/reviews/smells.md b/lenses/smells.md similarity index 100% rename from reviews/smells.md rename to lenses/smells.md diff --git a/modules/ai-skills.nix b/modules/ai-skills.nix index ba3eb4a..32dc35d 100644 --- a/modules/ai-skills.nix +++ b/modules/ai-skills.nix @@ -5,6 +5,9 @@ with lib; let cfg = config.services.ai-skills; + # Derive repo root from skillsPath (skills/ is a subdirectory) + repoRoot = dirOf cfg.skillsPath; + skillsList = '' Available skills: - niri-window-capture: Invisibly capture window screenshots @@ -40,6 +43,20 @@ in { description = "Skills to deploy to OpenCode (~/.config/opencode/skills/). ${skillsList}"; example = [ "worklog" "web-search" ]; }; + + # Lenses for orch multi-model review + enableLenses = mkOption { + type = types.bool; + default = true; + description = "Deploy review lenses to ~/.config/lenses/"; + }; + + # Workflows (beads protos) + enableWorkflows = mkOption { + type = types.bool; + default = true; + description = "Deploy workflow protos to ~/.beads/molecules.jsonl"; + }; }; config = mkIf cfg.enable { @@ -69,6 +86,21 @@ in { }) cfg.openCodeSkills ) )) + + # Lenses for orch + (mkIf cfg.enableLenses { + ".config/lenses" = { + source = "${repoRoot}/lenses"; + recursive = true; + }; + }) + + # Workflows (beads protos) + (mkIf cfg.enableWorkflows { + ".beads/molecules.jsonl" = { + source = "${repoRoot}/workflows/molecules.jsonl"; + }; + }) ]; }; } diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 0000000..6a0f3c1 --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,45 @@ +# Workflows + +Beads molecule templates (protos) for structured agent workflows. + +## Concept + +- **Proto**: A template workflow that can be instantiated +- **Molecule**: A persistent instance of a proto +- **Wisp**: An ephemeral instance (local-only, not synced) + +## Available Protos + +| ID | Name | Variables | +|----|------|-----------| +| `skills-fvc` | Code Review: {{target}} | `target` | + +## Usage + +**Spawn as wisp (ephemeral):** +```bash +bd wisp create skills-fvc --var target=src/main.py +``` + +**Pour as molecule (persistent):** +```bash +bd pour skills-fvc --var target=src/main.py +``` + +**After completion:** +```bash +bd mol squash # Compress to digest +bd mol burn # Delete without trace +``` + +## Deployment + +These protos are deployed to `~/.beads/molecules.jsonl` via home-manager, +making them available in any repository. + +## Creating New Protos + +1. Create an epic with child tasks using `bd create` +2. Use `{{variable}}` placeholders in titles/descriptions +3. Add the template label: `bd label add template` +4. Export to `workflows/molecules.jsonl` diff --git a/workflows/molecules.jsonl b/workflows/molecules.jsonl new file mode 100644 index 0000000..04e836c --- /dev/null +++ b/workflows/molecules.jsonl @@ -0,0 +1,7 @@ +{"id":"skills-fvc","title":"Code Review: {{target}}","description":"Multi-lens code review workflow for {{target}}.\n\n## Variables\n- target: File or directory to review\n\n## Workflow\n1. Run each lens via orch consensus (flash + gemini)\n2. Analyze findings\n3. File actionable items as beads\n4. Summarize findings in digest\n\n## Lenses\n- bloat: size, complexity, SRP violations\n- smells: readability, naming, control flow\n- dead-code: unused, unreachable, obsolete\n- redundancy: duplication, YAGNI, parallel systems","status":"open","priority":2,"issue_type":"epic","created_at":"2025-12-25T10:10:57.652098447-05:00","updated_at":"2025-12-25T10:10:57.652098447-05:00","labels":["template"]} +{"id":"skills-fvc.1","title":"Run bloat lens on {{target}}","description":"Run bloat review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/bloat.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: file size, function length, complexity, SRP violations.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:13:59.789715667-05:00","updated_at":"2025-12-26T01:15:59.453348311-05:00","dependencies":[{"issue_id":"skills-fvc.1","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:13:59.80248308-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.2","title":"Run smells lens on {{target}}","description":"Run smells review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/smells.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: naming issues, control flow smells, data smells, structural issues.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:13.977562568-05:00","updated_at":"2025-12-26T01:16:43.064403777-05:00","dependencies":[{"issue_id":"skills-fvc.2","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:13.989662453-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.3","title":"Run dead-code lens on {{target}}","description":"Run dead-code review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/dead-code.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: zombie code, unreachable paths, obsolete shims, import cruft.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:17.522715411-05:00","updated_at":"2025-12-26T01:16:48.452520859-05:00","dependencies":[{"issue_id":"skills-fvc.3","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:17.53423496-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.4","title":"Run redundancy lens on {{target}}","description":"Run redundancy review lens via orch:\n\n```bash\norch consensus \"$(cat ~/.config/lenses/redundancy.md)\" flash gemini --file {{target}} --mode open\n```\n\nLook for: duplication, parallel systems, YAGNI violations, consolidation opportunities.\nRecord findings for later filing.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:21.94274481-05:00","updated_at":"2025-12-26T01:16:52.579297412-05:00","dependencies":[{"issue_id":"skills-fvc.4","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:21.956965459-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.5","title":"File findings as beads","description":"Review all lens findings and file actionable items as beads:\n\nFor each HIGH/MED severity finding:\n```bash\nbd create --title=\"{{target}}: \u003cissue\u003e\" --type=task --priority=3 --body=\"Found by \u003clens\u003e lens review. \u003cdetails\u003e\"\n```\n\nGroup related findings. Skip LOW severity unless pattern emerges.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:34.288221353-05:00","updated_at":"2025-12-25T10:16:34.288221353-05:00","dependencies":[{"issue_id":"skills-fvc.5","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:34.303313556-05:00","created_by":"daemon"}]} +{"id":"skills-fvc.6","title":"Summarize review findings","description":"Create summary of code review findings for {{target}}:\n\n- Total findings by severity (HIGH/MED/LOW)\n- Top issues by category\n- Recommendations for immediate action\n- Technical debt assessment\n\nThis summary will become the squash digest.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T10:16:34.590409022-05:00","updated_at":"2025-12-25T10:16:34.590409022-05:00","dependencies":[{"issue_id":"skills-fvc.6","depends_on_id":"skills-fvc","type":"parent-child","created_at":"2025-12-25T10:16:34.591813242-05:00","created_by":"daemon"}]}