commit 8d34426864c5a3b7c4ce3bec3edab5a37c331deb Author: m3ta-chiron Date: Sat Aug 22 21:41:05 2026 +0200 chore: preserve beads tracker and adopt Go gitignore after python-era reset diff --git a/.beads/.gitignore b/.beads/.gitignore new file mode 100644 index 0000000..304f708 --- /dev/null +++ b/.beads/.gitignore @@ -0,0 +1,70 @@ +# Dolt database (managed by Dolt, not git) +dolt/ +embeddeddolt/ + +# Runtime files +bd.sock +bd.sock.startlock +sync-state.json +last-touched +.exclusive-lock + +# Daemon runtime (lock, log, pid) +daemon.* + +# Push state (runtime, per-machine) +push-state.json + +# Lock files (various runtime locks) +*.lock + +# Credential key (encryption key for federation peer auth — never commit) +.beads-credential-key + +# Local version tracking (prevents upgrade notification spam after git ops) +.local_version + +# Worktree redirect file (contains relative path to main repo's .beads/) +# Must not be committed as paths would be wrong in other clones +redirect + +# Sync state (local-only, per-machine) +# These files are machine-specific and should not be shared across clones +.sync.lock +export-state/ +export-state.json + +# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned) +ephemeral.sqlite3 +ephemeral.sqlite3-journal +ephemeral.sqlite3-wal +ephemeral.sqlite3-shm + +# Dolt server management (auto-started by bd) +dolt-server.pid +dolt-server.log +dolt-server.lock +dolt-server.port +dolt-server.activity + +# Corrupt backup directories (created by bd doctor --fix recovery) +*.corrupt.backup/ + +# Backup data (auto-exported JSONL, local-only) +backup/ + +# Per-project environment file (Dolt connection config, GH#2520) +.env + +# Legacy files (from pre-Dolt versions) +*.db +*.db?* +*.db-journal +*.db-wal +*.db-shm +db.sqlite +bd.db +# NOTE: Do NOT add negation patterns here. +# They would override fork protection in .git/info/exclude. +# Config files (metadata.json, config.yaml) are tracked by git by default +# since no pattern above ignores them. diff --git a/.beads/README.md b/.beads/README.md new file mode 100644 index 0000000..dbfe363 --- /dev/null +++ b/.beads/README.md @@ -0,0 +1,81 @@ +# Beads - AI-Native Issue Tracking + +Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code. + +## What is Beads? + +Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git. + +**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads) + +## Quick Start + +### Essential Commands + +```bash +# Create new issues +bd create "Add user authentication" + +# View all issues +bd list + +# View issue details +bd show + +# Update issue status +bd update --claim +bd update --status done + +# Sync with Dolt remote +bd dolt push +``` + +### Working with Issues + +Issues in Beads are: +- **Git-native**: Stored in Dolt database with version control and branching +- **AI-friendly**: CLI-first design works perfectly with AI coding agents +- **Branch-aware**: Issues can follow your branch workflow +- **Always in sync**: Auto-syncs with your commits + +## Why Beads? + +✨ **AI-Native Design** +- Built specifically for AI-assisted development workflows +- CLI-first interface works seamlessly with AI coding agents +- No context switching to web UIs + +🚀 **Developer Focused** +- Issues live in your repo, right next to your code +- Works offline, syncs when you push +- Fast, lightweight, and stays out of your way + +🔧 **Git Integration** +- Automatic sync with git commits +- Branch-aware issue tracking +- Dolt-native three-way merge resolution + +## Get Started with Beads + +Try Beads in your own projects: + +```bash +# Install Beads +curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + +# Initialize in your repo +bd init + +# Create your first issue +bd create "Try out Beads" +``` + +## Learn More + +- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs) +- **Quick Start Guide**: Run `bd quickstart` +- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples) + +--- + +*Beads: Issue tracking that moves at the speed of thought* ⚡ diff --git a/.beads/config.yaml b/.beads/config.yaml new file mode 100644 index 0000000..11d56fd --- /dev/null +++ b/.beads/config.yaml @@ -0,0 +1 @@ +no-git-ops: true diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl new file mode 100644 index 0000000..42ca452 --- /dev/null +++ b/.beads/interactions.jsonl @@ -0,0 +1,13 @@ +{"id":"int-58dc40ee","kind":"field_change","created_at":"2026-05-28T06:40:53.266160436Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-c96014b1","kind":"field_change","created_at":"2026-05-28T06:51:57.995522933Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.2","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-8ec2fe7f","kind":"field_change","created_at":"2026-05-28T06:57:14.054839388Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-5ef02067","kind":"field_change","created_at":"2026-05-28T07:00:18.483464037Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-b12d010f","kind":"field_change","created_at":"2026-05-28T07:15:22.597226799Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-4608df17","kind":"field_change","created_at":"2026-05-28T07:20:45.404215963Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-8a35ddbf","kind":"field_change","created_at":"2026-05-28T07:23:24.229234781Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.7","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-af8bd7ce","kind":"field_change","created_at":"2026-05-28T07:24:47.032378976Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.8","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-e6245ea7","kind":"field_change","created_at":"2026-05-28T07:39:25.408163902Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.9","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-3d420466","kind":"field_change","created_at":"2026-05-28T07:46:27.577138032Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.10","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}} +{"id":"int-f444e5d1","kind":"field_change","created_at":"2026-05-28T08:13:14.820734703Z","actor":"m3ta-chiron","issue_id":"agent-lib-4wx.11","extra":{"field":"status","new_value":"closed","old_value":"in_progress"}} +{"id":"int-b1779011c451e8aecfac8a15e2c332b8","kind":"field_change","created_at":"2026-06-13T07:55:57.404556723Z","actor":"m3ta-chiron","issue_id":"agent-lib-j6b","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Architecture review report written and opened: /tmp/architecture-review-20260613-075521.html"}} +{"id":"int-eaab83169be77c1e6a853e502b70362f","kind":"field_change","created_at":"2026-06-13T08:17:27.20786458Z","actor":"m3ta-chiron","issue_id":"agent-lib-feu","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Babysitter Deployment Plan exploration completed. Artifact: .a5c/deployment-plan-exploration.md. Run: 01KV00D3F73F6KY5Q8W4TFER5X"}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 0000000..3f44884 --- /dev/null +++ b/.beads/issues.jsonl @@ -0,0 +1,12 @@ +{"_type":"issue","id":"agent-lib-4wx.11","title":"Deliver end-to-end documentation and release gate","description":"Finish the MVP by documenting the full workflow and proving it through an offline end-to-end acceptance path. The slice should provide README content, quickstart, CLI reference, Home Manager examples, security/trust notes, troubleshooting, and a release gate that demonstrates init, Source add, inspect, snippet, Home Manager eval/render, target Manifests, and a green offline check.","acceptance_criteria":"- Documentation covers installation, quickstart, CLI reference, Home Manager configuration, Lockfile behavior, discovery conventions, security/trust model, troubleshooting, MVP scope, and non-goals\n- An offline end-to-end fixture workflow demonstrates initialization, Source discovery, selection, Pi and Opencode Rendered output, target Manifests, and no unmanaged overwrites\n- nix flake check is green without external network access and verifies the MVP acceptance criteria","notes":"E2E fixture check green. All steps verified: init creates lockfile, discover finds all items, lockfile has rev/narHash/HM-compatible schema, inspect/snippet/validate commands work, managed-file protection present. nix flake check passes.","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:50:02Z","created_by":"m3tam3re","updated_at":"2026-05-28T08:13:15Z","started_at":"2026-05-28T07:46:50Z","closed_at":"2026-05-28T08:13:15Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:50:01Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.10","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.9","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":10,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.10","title":"Complete CLI operational workflows and snippets","description":"Complete the day-to-day CLI workflow around existing Sources, Profiles, and Targets. The slice should make update/review/switch workflows practical with added/removed Item reports, offline and fetch validation modes, minimal and full Nix snippets, JSON output, non-interactive defaults, and an optional interactive entry point without automatic Nix edits.","acceptance_criteria":"- source update and source update --all report added and removed Items without changing Home Manager selection\n- validate runs offline by default, validate --fetch performs explicit reachability checks, and list/inspect/validate support stable JSON output\n- snippet emits both minimal Profile include snippets and full example configuration, while the CLI remains non-interactive by default and never edits Nix files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:57Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:46:28Z","started_at":"2026-05-28T07:39:36Z","closed_at":"2026-05-28T07:46:28Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:56Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":4,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.9","title":"Apply item-specific patches and deployment safety controls","description":"Add safety and customization controls around selected Items, including item-specific patches, target-specific overrides, targetName collision handling, editable-copy escape hatch, license propagation, and configurable incompatibility policy. The slice should prove that patches affect only copied Artifacts and never mutate original source content.","acceptance_criteria":"- Item-specific patches apply only to copied Artifacts, while original Canonical source content remains immutable and auditable\n- targetName overrides, target-specific enable/disable overrides, collision detection, and onIncompatible policies are enforced for both Pi and Opencode\n- License files, provenance headers for rendered Markdown, preserved file permissions, and editable-copy deployment mode are covered by tests","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:51Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:39:25Z","started_at":"2026-05-28T07:25:13Z","closed_at":"2026-05-28T07:39:25Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:51Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:52Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:52Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.8","title":"Deploy selected Items to the Pi Target","description":"Create the first Rendered output path for Pi, from selected Canonical Artifacts through the Pi Adapter into a target Manifest and deployable Linux/XDG target structure. The slice should support Skills, Prompts, and Agent Definitions as far as the verified Pi contract allows, while failing on incompatible Items.","acceptance_criteria":"- A selected Skill, Prompt, and Agent Definition can be rendered or deployed to the Pi Target according to the verified Adapter contract\n- The Pi Manifest records Source, Item identifier, content type, targetName, rev, narHash, and adapterVersion for every deployed Item\n- The deployment path is read-only/symlink-oriented by default, includes provenance for rendered files, and never overwrites unmanaged files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:47Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:24:47Z","started_at":"2026-05-28T07:23:38Z","closed_at":"2026-05-28T07:24:47Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.8","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:46Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.8","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:49:47Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.8","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:49:47Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":2,"dependent_count":3,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.7","title":"Deploy selected Items to the Opencode Target","description":"Create the first Rendered output path for Opencode, from selected Canonical Artifacts through the Opencode Adapter into a target Manifest and deployable Linux/XDG target structure. The slice should support Skills, Prompts, and Agent Definitions as far as the verified Opencode contract allows, while failing on incompatible Items.","acceptance_criteria":"- A selected Skill, Prompt, and Agent Definition can be rendered or deployed to the Opencode Target according to the verified Adapter contract\n- The Opencode Manifest records Source, Item identifier, content type, targetName, rev, narHash, and adapterVersion for every deployed Item\n- The deployment path is read-only/symlink-oriented by default, includes provenance for rendered files, and never overwrites unmanaged files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:42Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:23:24Z","started_at":"2026-05-28T07:21:06Z","closed_at":"2026-05-28T07:23:24Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.7","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:41Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.7","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:49:42Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.7","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:49:42Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":2,"dependent_count":3,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.6","title":"Verify Target Adapter contracts and scaffold the registry","description":"Establish the Target Adapter Registry and verify the native Target contracts for Pi and Opencode before rendering any real output. The slice should encode supported content types, adapterVersion, Linux/XDG default paths, compatibility rules, and scaffold Crush/Amp as known but not implemented Targets.","acceptance_criteria":"- Pi and Opencode Target conventions are researched, documented in the implementation, and represented as Adapter metadata with adapterVersion\n- Crush and Amp are represented in the registry as scaffolded Targets that fail explicitly if enabled before implementation\n- Adapter compatibility and unsupported Target behavior are tested independently from the Home Manager deployment pipeline","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:37Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:20:45Z","started_at":"2026-05-28T07:15:42Z","closed_at":"2026-05-28T07:20:45Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.6","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:37Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.6","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:49:37Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":3,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.5","title":"Support all/include/exclude and Profile merge validation","description":"Extend the Selection Model to cover all supported selection semantics across multiple Profiles. The slice should normalize all/include/exclude, merge Profiles by union, reject ambiguous or conflicting selections, and expose the same fail-fast behavior through Home Manager evaluation and CLI validation where applicable.","acceptance_criteria":"- all, include, and exclude are normalized per Source and content type, with all=true plus include rejected and exclude allowed only with all=true\n- Multiple Profiles merge by union when compatible and fail when the same Item has conflicting overrides\n- Validation errors are precise and tested for unknown Sources, unknown Items, include/exclude conflicts, and incompatible selection semantics","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:32Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:15:23Z","started_at":"2026-05-28T07:07:23Z","closed_at":"2026-05-28T07:15:23Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.5","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:32Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.5","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:49:32Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.4","title":"Select one explicit Item into Canonical output","description":"Implement the first selected-Item path from Lockfile inventory through Profile include configuration into Canonical output. The slice should prove that explicit selection is required, unknown Sources/Items fail fast, target override data is preserved, and the selected Artifact remains a whole folder in Canonical output.","acceptance_criteria":"- A Profile can explicitly include one Item from a Source and produce a Canonical output Artifact for it\n- No Item is selected by default, and unknown Source or Item references fail with errors that include Source, type, Item, and Profile context\n- The Canonical output preserves the whole Artifact folder, including references and permissions, without target-specific rendering","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:27Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:00:18Z","started_at":"2026-05-28T06:57:29Z","closed_at":"2026-05-28T07:00:18Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.4","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:27Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.4","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:49:27Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":4,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.3","title":"Add and update reproducible Git Sources","description":"Add the first reproducible Git Source workflow, from provider-neutral and known Web tree URLs through the Source Resolver into pinned Lockfile entries. The slice should resolve refs to rev/narHash, run Discovery, support update/remove/list/inspect/update-all, and report added/removed Items using local Git fixtures rather than external network tests.","acceptance_criteria":"- source add resolves a Git Source ref to rev and narHash, normalizes supported Web tree URLs, runs Discovery, and writes a deterministic Lockfile\n- source update, source update --all, source remove, source list, and source inspect preserve reproducibility and report Item inventory changes\n- Private repository credentials are never stored in the Lockfile, submodules are unsupported, and default tests use temporary local Git repositories","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:22Z","created_by":"m3tam3re","updated_at":"2026-05-28T06:57:14Z","started_at":"2026-05-28T06:52:15Z","closed_at":"2026-05-28T06:57:14Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.3","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:22Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.3","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:49:22Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.3","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:49:22Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":2,"dependent_count":2,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.2","title":"Discover a local fixture Source into a Lockfile inventory","description":"Create the first content-bearing path from a local fixture Source through the Discovery Engine into the Lockfile inventory. The slice should discover Skills, Prompts, Agent Definitions, and Tool Manifests as whole Artifacts with Entry files, Metadata, warnings, and license hints, then expose the result through CLI inspect/validate output and Home Manager inventory validation.","acceptance_criteria":"- A local fixture Source produces Lockfile Items for Skills, Prompts, Agent Definitions, and Tool Manifests, including nested Item identifiers\n- Discovery records Entry file, Artifact path, Metadata, warnings, and license file hints without executing any source content\n- CLI inspect and validate expose the discovered inventory in human-readable and JSON output, and tests run offline against fixtures","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:17Z","created_by":"m3tam3re","updated_at":"2026-05-28T06:51:58Z","started_at":"2026-05-28T06:41:02Z","closed_at":"2026-05-28T06:51:58Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.2","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:17Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.2","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:49:17Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":1,"dependent_count":3,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx.1","title":"Bootstrap the empty agent-lib installation path","description":"Establish the first demoable path through the empty project: a Nix flake, development shell, CLI entry point, empty Lockfile initialization, importable Home Manager module, fixture skeleton, and a green baseline check. This slice should prove that agent-lib can be installed, initialized, and validated without any real Source content yet.","acceptance_criteria":"- agent-lib init creates a deterministic empty Lockfile with the expected schema version and no active Items\n- The Home Manager module can be imported and evaluated with agent-lib disabled and enabled against an empty Lockfile\n- The project quality gate runs offline and covers the baseline CLI, Nix, formatting, and fixture skeleton","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:11Z","created_by":"m3tam3re","updated_at":"2026-05-28T06:40:53Z","started_at":"2026-05-27T18:00:14Z","closed_at":"2026-05-28T06:40:53Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.1","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:11Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":0,"dependent_count":4,"comment_count":0} +{"_type":"issue","id":"agent-lib-4wx","title":"agent-lib PRD v1.0","description":"Product Requirements Document for agent-lib: an agent-independent library infrastructure built on Nix flakes and Home Manager. See docs/prd.md for the full document.","notes":"# agent-lib: Product Requirements Document\n\n**Status:** Draft \n**Version:** 1.0\n\n---\n\n## Problem Statement\n\nUsers who rely on multiple AI agent runtimes — such as Pi, Opencode, Crush, and Amp — face a fragmented and manually maintained experience when it comes to managing skills, prompts, and agent definitions. Existing approaches are agent-specific: configurations are copied, modified, and versioned separately for each runtime. This makes it difficult to:\n\n- Share and reuse skills across different agent runtimes\n- Reproduce a consistent agent environment across machines and systems\n- Import content from external repositories in a controlled, reproducible way\n- Manage which content is active on which target platform\n\nThere is no unified, agent-independent abstraction layer that allows a user to manage a canonical library of skills, prompts, and agent definitions — and then deploy precisely selected subsets to specific runtime targets in a deterministic, declarative way.\n\n---\n\n## Solution\n\n**agent-lib** is an agent-independent library infrastructure built on Nix flakes and Home Manager. It provides:\n\n1. A **canonical model** for skills, prompts, agent definitions, and tool manifests — stored as structured artifacts, not agent-specific configs\n2. A **Python CLI** for managing source repositories, discovering items, and producing configuration snippets — without ever editing Nix files automatically\n3. A **Home Manager module** that consumes a versioned lockfile and declarative profile selections to produce target-specific deployment artifacts\n4. **Target adapters** for supported runtimes (Pi and Opencode in MVP; Crush and Amp scaffolded)\n5. A **provenance-aware deployment pipeline** that keeps original artifacts immutable and renders target-specific outputs separately\n\nThe result: a single declarative source of truth for your agent library, deployed reproducibly to any supported target.\n\n---\n\n## User Stories\n\n### Source Management\n\n1. As a user, I want to add an external Git repository as a source, so that I can import skills and other content from shared libraries.\n2. As a user, I want the CLI to automatically pin the current commit (rev) and narHash when adding a source, so that my library is reproducible.\n3. As a user, I want to optionally specify a branch or tag (ref) when adding a source, so that I can target a specific release line.\n4. As a user, I want the CLI to resolve the default branch when no ref is specified, so that I do not have to know the branch name in advance.\n5. As a user, I want the CLI to normalize GitHub/GitLab/Web tree URLs (e.g., `https://github.com/org/repo/tree/main/skills`) into provider-neutral git URLs, so that I can paste URLs directly from browser tabs.\n6. As a user, I want to update a source to the latest version of its ref, so that I can pull in upstream changes.\n7. As a user, I want `source update` to update both the rev/narHash and the full discovery inventory, so that pins and artifacts stay in sync.\n8. As a user, I want to update all sources at once with `source update --all`, so that I can refresh my entire library efficiently.\n9. As a user, I want to remove a source from the lockfile, so that I can clean up deprecated or unwanted repositories.\n10. As a user, I want the CLI to warn when a source is still referenced in my Home Manager configuration after removal, so that I am not surprised by Nix eval failures.\n11. As a user, I want to list all configured sources with their current rev and item counts, so that I can review my library at a glance.\n12. As a user, I want to inspect a specific source in detail, so that I can see what skills, prompts, agents, and tool manifests are available.\n13. As a user, I want the CLI to detect and report when a source already exists, so that I am not accidentally overwriting configurations.\n14. As a user, I want to force-add a source with `--force`, so that I can intentionally replace an existing source configuration.\n15. As a user, I want private Git repositories to work via external SSH/HTTPS credentials, so that I am not blocked from using proprietary or internal libraries.\n16. As a user, I want the CLI to never store secrets in the lockfile, so that my credentials are not leaked into version-controlled files.\n17. As a user, I want the CLI to not support submodules in the MVP, so that the implementation remains simple and predictable.\n\n### Discovery\n\n18. As a user, I want items to be discovered automatically by convention, so that I do not have to manually specify every file.\n19. As a user, I want skills to be discovered in `skills/\u003cid\u003e/SKILL.md`, prompts in `prompts/\u003cid\u003e/PROMPT.md`, and agent definitions in `agents/\u003cid\u003e/AGENT.md`, so that standard repository structures are recognized without configuration.\n20. As a user, I want recursive subdirectory discovery, so that nested skill and prompt collections work correctly.\n21. As a user, I want to override discovery paths per source, so that non-standard repositories can still be imported.\n22. As a user, I want the CLI to extract metadata from frontmatter (name, description, tags, requires), so that items carry useful context.\n23. As a user, I want invalid or malformed frontmatter to produce a warning, not a failure, so that discovery is resilient to minor format errors.\n24. As a user, I want discovery to respect explicit glob patterns for each content type, so that non-standard file extensions or locations can be supported.\n25. As a user, I want the lockfile to store the discovery rules used for each source, so that updates repeat exactly the same scan.\n26. As a user, I want tool manifests to be discovered (e.g., `tools/\u003cid\u003e/TOOL.md`), so that the inventory shows available tools even though deployment is not yet implemented.\n27. As a user, I want to see all discovery warnings in the lockfile and CLI output, so that I understand what the system found versus what it expected.\n28. As a user, I want to configure a local path as a source, so that I can manage my own skills and prompts alongside external repositories.\n\n### Lockfile\n\n29. As a user, I want the lockfile to be valid, versioned JSON, so that it is machine-readable and reviewer-friendly.\n30. As a user, I want the lockfile to contain schemaVersion, generatedBy, sources with rev/ref/narHash, discovery rules, and items inventory, so that the complete source of truth is captured.\n31. As a user, I want the lockfile to be deterministically formatted (sorted keys, stable field order), so that git diffs are clean and reviews are easy.\n32. As a user, I want the CLI to search upward from the current directory for an `agent-sources.lock.json`, so that I can run commands from subdirectories of my Home Manager repo.\n33. As a user, I want to override the lockfile path with `--lockfile`, so that I am never blocked by auto-detection.\n34. As a user, I want the lockfile to store provenance metadata including license file references, so that I can audit the legal status of imported content.\n35. As a user, I want the lockfile to record warnings but not fail on them, so that discovery remains robust.\n36. As a user, I want a single lockfile per agent-lib installation, so that the system is simple to reason about.\n\n### Selection and Profiles\n\n37. As a user, I want to select which items from a source are installed, so that I am in control of what ends up on my system.\n38. As a user, I want selection to be explicit by default, so that no content is installed without deliberate choice.\n39. As a user, I want to use `all = true` with `exclude` to select everything except a few items, so that large repositories can be partially activated conveniently.\n40. As a user, I want to use `include` as a simple list or as an attribute set with per-item overrides, so that both convenience and power are available.\n41. As a user, I want to rename a deployed item via `targetName`, so that I can avoid collisions or match my naming conventions.\n42. As a user, I want per-item target-specific overrides, so that a skill can be enabled on some targets and disabled on others.\n43. As a user, I want profile-based selection, so that I can have different library configurations for work and personal contexts.\n44. As a user, I want the default profile to be used when no profile is specified, so that simple setups work without extra configuration.\n45. As a user, I want profile merging to union includes, so that combining profiles does not silently drop content.\n46. As a user, I want conflicting overrides for the same item across profiles to fail fast, so that I am not surprised by silent last-wins behavior.\n47. As a user, I want `all = true` and `include` simultaneously to be an error, so that the semantics are never ambiguous.\n48. As a user, I want `exclude` to be allowed only when `all = true`, so that its meaning is clear.\n49. As a user, I want unknown items in include to be caught as errors, so that typos and stale references are detected early.\n50. As a user, I want `all = false` to be the default, so that nothing is installed unintentionally.\n\n### Deployment\n\n51. As a user, I want deployment to use read-only symlinks from the Nix store, so that the system is reproducible and cannot drift.\n52. As a user, I want an explicit escape hatch to enable editable copies, so that I can experiment locally without losing the deterministic default.\n53. As a user, I want the deployment to never overwrite existing unmanaged files, so that my manual configurations are preserved.\n54. As a user, I want a generated manifest per target that records source, itemId, type, targetName, rev, and narHash, so that I can audit what was deployed and why.\n55. As a user, I want rendered target files to carry a provenance header comment, so that I can trace content back to its source.\n56. As a user, I want original artifacts to remain immutable and separate from rendered outputs, so that debugging and auditing are straightforward.\n57. As a user, I want artifact folders to be copied as atomic units, so that relative references and related files stay together.\n58. As a user, I want file permissions from Git/Nix to be preserved, so that scripts and binaries remain functional.\n59. As a user, I want target adapter behavior to be documented with adapterVersion, so that I can reason about rendering changes over time.\n60. As a user, I want deployed items to include license files that were part of the source repository, so that provenance is complete.\n\n### Targets\n\n61. As a user, I want to enable Pi as a target, so that my skills and prompts are available in the Pi runtime.\n62. As a user, I want to enable Opencode as a target, so that my skills and prompts are available in the Opencode runtime.\n63. As a user, I want target paths to be configurable via Nix options, so that non-standard installations are supported.\n64. As a user, I want Linux/XDG paths as defaults, so that the standard setup works on typical Nix/Home Manager installations.\n65. As a user, I want inkompatible items to fail by default, so that I am not silently missing content I expected.\n66. As a user, I want an explicit override for onIncompatible to switch between error/warn/skip, so that I can handle edge cases deliberately.\n67. As a user, I want target-specific type mappings (e.g., prompts → commands on Pi), so that content is placed in the right location for each runtime.\n68. As a user, I want no implicit cross-type fallback (e.g., a prompt rendered as a skill), so that content semantics are preserved.\n69. As a user, I want target adapters for Crush and Amp to be scaffolded, so that the infrastructure is ready for future implementation.\n70. As a user, I want the build to produce a canonical output and a targets subdirectory, so that the structure is clean and debuggable.\n\n### CLI\n\n71. As a user, I want `agent-lib init` to create a new lockfile, so that I can start from scratch.\n72. As a user, I want `agent-lib source add \u003curl\u003e` to add a source with default branch detection, so that the workflow is minimal.\n73. As a user, I want to name a source explicitly with `--name`, so that I can control the identifier used in the lockfile and Nix configuration.\n74. As a user, I want to specify a root path with `--root`, so that I can import only a subdirectory of a repository.\n75. As a user, I want `agent-lib snippet` to output a ready-to-use Nix configuration snippet, so that I can copy it directly into my Home Manager config.\n76. As a user, I want `snippet` to support `--full` for a complete example and default to a minimal profile include, so that both convenience and precision are available.\n77. As a user, I want `agent-lib validate` to check lockfile schema, source consistency, and item existence offline, so that CI runs are fast and reliable.\n78. As a user, I want `validate --fetch` to additionally verify that sources are reachable, so that I can check network accessibility on demand.\n79. As a user, I want list, inspect, and validate to support `--json` output, so that CI tooling and scripts can consume the results.\n80. As a user, I want the CLI to never edit Nix configuration files automatically, so that I am always in control of my Home Manager setup.\n81. As a user, I want the CLI to be non-interactive by default, so that it works well in scripts and CI pipelines.\n82. As a user, I want an `--interactive` flag for interactive workflows, so that power users can have a richer experience when desired.\n\n### Validation and Error Handling\n\n83. As a user, I want unknown sources in my profile configuration to produce a clear error, so that typos are caught at eval time.\n84. As a user, I want unknown items in my selection to produce a clear error, so that stale references are caught early.\n85. As a user, I want name collisions at the target level to fail fast, so that duplicate deployments are not silently resolved incorrectly.\n86. As a user, I want include/exclude conflicts to produce an error, so that contradictory selections are not silently accepted.\n87. As a user, I want the Home Manager module to produce helpful error messages that include source, type, item, and target context, so that debugging is efficient.\n88. As a user, I want warnings to be emitted for non-critical issues such as malformed frontmatter or missing license files, so that I am informed without being blocked.\n\n### Testing and Quality\n\n89. As a user, I want offline fixture repositories for discovery and lockfile tests, so that tests run without network access.\n90. As a user, I want `nix flake check` to be the integration gate, so that all quality checks run in a single command.\n91. As a user, I want CLI commands to be tested against fixture inputs and expected JSON outputs, so that the surface area is well covered.\n92. As a user, I want target renderer behavior to be tested in isolation with mock artifacts, so that adapters are correct before end-to-end testing.\n93. As a user, I want Nix module eval smoke tests to verify that the Home Manager module loads and produces output, so that regressions in the module are caught.\n\n### Documentation and Operations\n\n94. As a user, I want a clear README with installation, quickstart, CLI reference, and security notes, so that I can get started quickly.\n95. As a user, I want the PRD to define the MVP contract explicitly, so that I know what is and is not supported.\n96. As a user, I want a glossary of terms (Source, Item, Target, Adapter, Manifest, Profile, etc.), so that the domain vocabulary is unambiguous.\n97. As a user, I want an operational workflow guide for add/update/review/switch, so that the day-to-day usage pattern is clear.\n98. As a user, I want the system to produce clear added/removed item reports on update, so that I can review changes before committing.\n\n---\n\n## Implementation Decisions\n\n### Architecture and Core Model\n\n**1. Canonical Agent-Independent Model**\n\nThe library uses a canonical internal model (Skill, Prompt, Agent Definition, Tool Manifest) that is independent of any specific runtime target. Adapters transform canonical artifacts into target-specific formats. This avoids vendor lock-in and ensures that new targets can be added by implementing an adapter without changing the source content.\n\n**2. Nix Flake + Home Manager Module**\n\nThe infrastructure is built on Nix flakes for the development environment and reproducibility, and on Home Manager modules for declarative configuration and deployment. The flake provides the CLI package as an app, the HM module as a module output, and standard devShell/checks/formatter outputs.\n\n**3. Source Model**\n\nExternal sources are Git repositories identified by provider-neutral git URLs. Sources are pinned to a specific `rev` with `narHash` for reproducibility. An optional `ref` (branch/tag) is stored to enable `source update` to resolve new revisions. Sources do not contain secrets; authentication uses the user's existing Git credentials.\n\n**4. Discovery Rules in Lockfile**\n\nDiscovery rules (paths, include globs) are stored in the lockfile as part of each source entry, not in the Home Manager configuration. This ensures that `source update` repeats exactly the same scan that was used for the original discovery. Selection remains in Home Manager.\n\n**5. Original Artifacts Immutable**\n\nCanonical artifacts are stored unchanged. Any target-specific rendering produces separate rendered output. Patches are explicit user-selected transformations applied to item copies, never silent modifications of upstream originals.\n\n**6. Symlink/Read-Only Deployment Default**\n\nDeployment uses read-only symlinks from the Nix store by default. An explicit escape hatch enables editable copies. No existing unmanaged files are overwritten.\n\n### Modules\n\n**Source Resolver**\n\nNormalizes Git/Web tree URLs to provider-neutral git URLs. Resolves `ref` to `rev` and `narHash` using Nix-native prefetching. Stores `url`, `ref`, `rev`, `narHash` in the lockfile. Detects private repo access requirements.\n\n**Lockfile Manager**\n\nReads and writes versioned JSON lockfiles. Validates schemaVersion. Produces deterministic output with sorted keys and stable field ordering. Tracks `generatedBy` and `schemaVersion`. Stores discovery rules, item inventories, warnings, and license references per source.\n\n**Discovery Engine** *(deep module)*\n\nRecursively finds items by type in a source tree. Identifies entry files (SKILL.md, PROMPT.md, AGENT.md, TOOL.md, JSON alternatives). Extracts frontmatter metadata (name, description, tags, requires). Records warnings for format issues. Applies configurable glob patterns per content type. Runs in isolation against a source tree; no network access required.\n\n**Selection Model** *(deep module)*\n\nNormalizes `all/include/exclude` for each source and content type. Validates selections against the lockfile inventory. Resolves profile merging with conflict detection. Applies per-item target overrides. Produces a consolidated selection map for the canonical builder. Must be testable without any target adapter.\n\n**Canonical Artifact Builder**\n\nCopies selected items from sources into a canonical output directory. Applies item-specific patches from the Nix selection to copies, leaving originals untouched. Preserves whole artifact folders including references, scripts, and assets. Detects and records license files.\n\n**Target Adapter Registry**\n\nMaintains adapter metadata for each supported target (Pi, Opencode, Crush, Amp). Records supported content types, adapterVersion, default paths, and rendering rules. Provides a registry interface used by the Home Manager module to route items to the correct renderer.\n\n**Target Renderers** *(deep module, one per target)*\n\nEach renderer takes canonical artifacts and a target configuration and produces rendered output for its target. Handles target-specific format conversion, path layout, and provenance headers. Fails fast on incompatible items unless an override is set. Produces a per-target manifest.\n\n**Home Manager Module**\n\nProvides `programs.agent-lib` Nix options. Loads and validates the lockfile. Resolves profile selections and applies merging. Validates sources, items, and targets. Orchestrates the canonical builder and target renderers. Configures symlinks into native target paths. Produces manifests and error messages with full context.\n\n**CLI**\n\nCommands: `init`, `source add`, `source update`, `source remove`, `source list`, `source inspect`, `snippet`, `validate`. Uses Typer for subcommands, Pydantic for lockfile schemas, PyYAML for frontmatter extraction, and subprocess calls to `nix flake prefetch`/`nix-prefetch-git` for fetching. Never edits Nix files. Outputs JSON for list/inspect/validate with `--json` flag. Non-interactive by default, `--interactive` for optional rich mode.\n\n**Test Fixtures**\n\nSimple fixture repository with nested skills, prompts, agent definitions, and a tool manifest. Problematic fixture repository with duplicate names, invalid frontmatter, and multiple-entry directories. Temporary local Git repositories created during Git-specific CLI tests.\n\n### Lockfile Schema\n\nThe lockfile is versioned JSON with the following top-level structure:\n\n```jsonc\n{\n \"schemaVersion\": 1,\n \"generatedBy\": \"agent-lib\",\n \"sources\": {\n \"\u003csourceName\u003e\": {\n \"type\": \"git\",\n \"url\": \"\u003cprovider-neutral git URL\u003e\",\n \"ref\": \"\u003cbranch or tag, optional\u003e\",\n \"rev\": \"\u003cpinned commit\u003e\",\n \"narHash\": \"\u003cnix narHash\u003e\",\n \"root\": \"\u003cpath within repo, default .\u003e\",\n \"discovery\": {\n \"skills\": { \"paths\": [], \"include\": [] },\n \"prompts\": { \"paths\": [], \"include\": [] },\n \"agents\": { \"paths\": [], \"include\": [] },\n \"tools\": { \"paths\": [], \"include\": [] }\n },\n \"items\": {\n \"skills\": {\n \"\u003citemId\u003e\": { \"path\": \"\", \"entry\": \"\", \"metadata\": {}, \"licenseFiles\": [] }\n },\n \"prompts\": { ... },\n \"agents\": { ... },\n \"tools\": { ... }\n },\n \"warnings\": []\n }\n }\n}\n```\n\n### Nix Options Schema (Proposed API)\n\n```nix\nprograms.agent-lib = {\n enable = true;\n lockFile = ./agent-sources.lock.json;\n\n targets.\u003ctargetName\u003e = {\n enable = true;\n profiles = [ \"default\" ];\n configDir = \"\u003coverride path\u003e\";\n };\n\n profiles.\u003cprofileName\u003e.sources.\u003csourceName\u003e = {\n skills = {\n all = false; # default\n # OR: all = true; exclude = [];\n # OR: include = [ \"item-a\" \"item-b\" ];\n # OR: include = {\n # \"item-a\" = {};\n # \"item-b\" = { targetName = \"renamed\"; targets.\u003ctarget\u003e.enable = false; };\n # };\n };\n prompts.include = [ ... ];\n agents.include = [ ... ];\n };\n};\n```\n\n### CLI Commands\n\n| Command | Description |\n|---|---|\n| `init` | Initialize a new lockfile in the current directory |\n| `source add \u003curl\u003e` | Add a source, resolve ref/rev/narHash, discover items, write to lockfile |\n| `source update \u003cname\u003e` | Update a single source to latest ref |\n| `source update --all` | Update all sources with updateable refs |\n| `source remove \u003cname\u003e` | Remove a source from the lockfile |\n| `source list` | List all sources with rev and item counts |\n| `source inspect \u003cname\u003e` | Show detailed item inventory for a source |\n| `snippet \u003csource\u003e` | Output Nix configuration snippet |\n| `validate` | Validate lockfile schema and source consistency (offline) |\n| `validate --fetch` | Additionally verify source reachability |\n\n### Milestones\n\n- **M0 Foundation:** Repo structure, flake, devShell, checks skeleton, fixtures, README skeleton\n- **M1 CLI Core:** Lockfile models, init/add/inspect/list/update/remove/validate/snippets\n- **M2 Discovery:** Recursive item discovery, metadata extraction, warnings, tool manifest discovery\n- **M3 Nix Core:** Lockfile loading, selection normalization, profile merging, validation/assertions, canonical/target output generation\n- **M4 Targets:** Researched and implemented Pi and Opencode adapters\n- **M5 E2E + Docs:** Fixture-based eval/render tests, README, PRD acceptance criteria verified\n\nResearch into actual Pi and Opencode target paths and formats must be completed before or during M4.\n\n---\n\n## Testing Decisions\n\n**Test Philosophy**\n\nTests verify external observable behavior, not internal implementation details. Modules are tested at their public interfaces. Integration tests use fixture repositories and do not require network access in the default check run.\n\n**Modules to Test**\n\nAll modules require tests:\n\n- **Source Resolver:** URL normalization, ref/rev/Hash resolution, Git tree URL parsing, error handling for invalid URLs\n- **Lockfile Manager:** Schema validation, round-trip read/write, deterministic output, migration handling\n- **Discovery Engine (deep module):** Recursive item finding, type identification, frontmatter extraction, warning generation, glob pattern matching, nested directories, empty sources\n- **Selection Model (deep module):** all/include/exclude normalization, profile merging, conflict detection, unknown item detection, target override application\n- **Canonical Artifact Builder:** Whole-folder copy, patch application to copies only, license file detection, symlink/read-only behavior\n- **Target Renderers (deep module, per target):** Format rendering, path layout, provenance headers, incompatibility fail-fast, manifest generation\n- **Home Manager Module:** Eval smoke test, option validation, assertion messages, target configuration\n- **CLI:** External behavior of all commands, JSON output format, error messages, non-interactive defaults\n\n**Test Infrastructure**\n\n- Fixture repos in `fixtures/repos/` with known item sets including normal and problematic content\n- Temporary local Git repositories created during Git-specific CLI tests to avoid network dependency\n- `nix flake check` as the single integration gate covering Nix formatting, module eval, and Python linting/type checking\n- Offline test suite: no network calls in default checks; `--fetch` variant for optional online validation\n- Prior art: standard Python unit test patterns (pytest), Nix module eval smoke tests, fixture-based integration testing\n\n**Acceptance Test Pattern**\n\n```\nGiven a lockfile with source \"superpowers\"\nAnd profile default includes skill \"writing-plans\"\nWhen home-manager switch runs\nThen the Opencode target contains a symlink for \"writing-plans\"\nAnd the target manifest records source \"superpowers\", itemId \"writing-plans\", and rev \"...\"\n```\n\n---\n\n## Out of Scope\n\nThe following are explicitly not planned for the MVP and should not be added without a separate decision:\n\n- Tool deployment or tool execution (Tool Manifests are discovered but not deployed)\n- Submodules in any form\n- Automatic editing of Nix configuration files by the CLI\n- Template generator / `agent-lib new` command\n- Additional configuration file (e.g., `agent-lib.toml`)\n- Multiple lockfiles per profile or per installation\n- NixOS system module (Home Manager User-level only)\n- Automatic migration of existing agent configurations\n- Curated or official content library shipped with agent-lib\n- Implicit cross-type fallback (e.g., rendering a prompt as a skill)\n- Native Windows or non-Nix/non-Home-Manager installation\n- Full semantic normalization of agent definition schemas\n- Automatic dependency resolution between items\n- macOS-specific default paths (Linux/XDG defaults only in MVP)\n- Automatic license enforcement or legal review\n\n---\n\n## Further Notes\n\n**Glossary**\n\n| Term | Definition |\n|---|---|\n| Source | An external Git repository or local path that provides library content |\n| Lockfile | Versioned JSON file (`agent-sources.lock.json`) containing pins, discovery rules, and item inventory |\n| Item | A single discovered entity of a given type (Skill, Prompt, Agent Definition, Tool Manifest) |\n| Artifact | A complete item folder including entry file, references, scripts, and assets |\n| Entry file | The primary file that identifies an item (SKILL.md, PROMPT.md, AGENT.md, TOOL.md) |\n| Metadata | Frontmatter and file-level information extracted from an item (name, description, tags, requires) |\n| Profile | A named collection of source selections that can be activated on specific targets |\n| Target | A supported runtime/configuration destination (Pi, Opencode, Crush, Amp) |\n| Adapter | A target-specific module that renders canonical artifacts into native target format |\n| Manifest | A generated file per target that records what was deployed, from which source, and at which revision |\n| Canonical output | The immutable, original artifact output produced by the Canonical Artifact Builder |\n| Rendered output | Target-specific transformed output produced by a Target Renderer |\n| Agent Definition | An imported content item that defines a persona, role, or agent configuration |\n| Tool Manifest | A discovered item describing an available tool (not deployed in MVP) |\n\n**Security and Trust Model**\n\nExternal sources are untrusted by default. Adding or updating a source does not activate any content. Activation requires explicit selection in a Home Manager profile. The CLI never stores secrets in the lockfile. The discovery process is read-only; no source scripts are executed during discovery. Tool manifests are discovered but not deployed in the MVP. Users are responsible for the legal status and licensing of imported external content.\n\n**No ADR Files Found**\n\nAt time of PRD creation, no ADR files were found in the repository. Future architectural decisions should be captured as ADRs using a standard format if needed.\n\n**Post-MVP Candidates**\n\nThe following are identified for future consideration but are not in the MVP scope:\n\n- Native Crush and Amp target adapters\n- Tool deployment with explicit trust model\n- Template generator / `agent-lib new` command\n- Full semantic Agent Definition normalization\n- Automatic dependency resolution\n- macOS-specific default paths\n- Curated content library\n- Source-wide patches/overlays\n","status":"open","priority":2,"issue_type":"epic","owner":"p@m3ta.dev","created_at":"2026-05-27T17:35:23Z","created_by":"m3tam3re","updated_at":"2026-05-27T17:35:33Z","labels":["ready-for-agent"],"dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/.beads/metadata.json b/.beads/metadata.json new file mode 100644 index 0000000..6b6d9f1 --- /dev/null +++ b/.beads/metadata.json @@ -0,0 +1,7 @@ +{ + "database": "dolt", + "backend": "dolt", + "dolt_mode": "embedded", + "dolt_database": "agent_lib", + "project_id": "379983ee-9720-40e7-a662-3872246af82f" +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3bd1c20 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +# Beads / Dolt files (added by bd init) +.dolt/ +*.db +.beads-credential-key + +# Go build artifacts +agent-lib +agent-lib.exe +dist/ +*.test +*.out +coverage.* + +# Editor/IDE +*.swp +*.swo +*~ +.fuse_hidden* +.DS_Store +.idea/ +.vscode/ +*.code-workspace + +# Local env overrides (never commit) +.env +.env.local