{"id":42492267,"url":"https://github.com/diogocnunes/ai-shadow-vault","last_synced_at":"2026-04-02T13:59:33.872Z","repository":{"id":332806929,"uuid":"1129998666","full_name":"diogocnunes/ai-shadow-vault","owner":"diogocnunes","description":"AI Shadow Vault is a local, pack-first DX infrastructure for AI coding. Keep AI context outside Git, enforce consistent workflows, and add stack expertise via official packs (starting with Laravel).","archived":false,"fork":false,"pushed_at":"2026-03-26T07:32:25.000Z","size":3750,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T17:08:42.357Z","etag":null,"topics":["ai","automation","developer-experience","gemini","laravel","productivity","zsh","zshrc"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diogocnunes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T22:12:13.000Z","updated_at":"2026-03-26T07:32:23.000Z","dependencies_parsed_at":"2026-03-10T23:00:59.843Z","dependency_job_id":null,"html_url":"https://github.com/diogocnunes/ai-shadow-vault","commit_stats":null,"previous_names":["diogocnunes/ai-shadow-vault"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/diogocnunes/ai-shadow-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diogocnunes%2Fai-shadow-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diogocnunes%2Fai-shadow-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diogocnunes%2Fai-shadow-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diogocnunes%2Fai-shadow-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diogocnunes","download_url":"https://codeload.github.com/diogocnunes/ai-shadow-vault/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diogocnunes%2Fai-shadow-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","developer-experience","gemini","laravel","productivity","zsh","zshrc"],"created_at":"2026-01-28T12:24:29.439Z","updated_at":"2026-04-02T13:59:33.864Z","avatar_url":"https://github.com/diogocnunes.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Shadow Vault\n\n👉 Just want to get started fast? → see [LAZY.md](LAZY.md)\n\nAI Shadow Vault is a local developer-experience infrastructure for AI-assisted coding.\n\nIt keeps AI context outside your Git repository and injects only the runtime files each project needs.\n\n## What This Package Is\n\nAI Shadow Vault is a ZSH-based local system that standardizes:\n\n- project rules and guardrails\n- task and context files\n- agent memory/session flow\n- optional stack-specific skills through packs\n\nIt is not a cloud service, not a hosted agent, and not a framework plugin.\n\n## Why It Exists\n\nMost teams hit the same problems when using AI tools in real projects:\n\n- context files pollute Git history\n- private notes leak into repositories\n- each project ends up with inconsistent AI conventions\n- prompts drift and quality drops over time\n\nAI Shadow Vault solves this by separating infrastructure (core) from stack expertise (packs).\n\n## Who It Is For\n\n- developers using Claude/Codex/Gemini in daily coding workflows\n- teams that want repeatable AI project setup\n- maintainers who need strict local control over context and privacy\n\n## Vision and Values\n\nAI Shadow Vault is built around four values:\n\n1. Privacy by default: local-first context, no mandatory cloud dependency.\n2. Predictability over magic: explicit files, explicit commands, explicit contracts.\n3. Maintainability at scale: core stays generic; stack intelligence lives in packs.\n4. Low-friction adoption: works with existing repositories without forcing rewrites.\n\n## What Changed in v5 (Hard Cut)\n\nFrom `v5.0.0` onward, core no longer provides moved skills through legacy fallback.\n\nIf a skill was moved to the Laravel pack, core now returns:\n\n- `ASV-HARD-MIGRATION-001`\n\nThis hard cut was intentional to:\n\n- remove the misleading “Laravel-first core” perception\n- make the core genuinely stack-agnostic\n- enforce one source of truth for Laravel skills (`ai-shadow-vault-laravel`)\n\n## Installation\n\n```bash\ngit clone https://github.com/diogocnunes/ai-shadow-vault.git ~/.ai-shadow-vault\nmkdir -p ~/.ai-shadow-vault-data\n\n# Add to ~/.zshrc\nsource ~/.ai-shadow-vault/scripts/shell_integration.zsh\n\n# Reload shell\nsource ~/.zshrc\n```\n\n## Update\n\n```bash\nvault-update\nsource ~/.ai-shadow-vault/scripts/shell_integration.zsh\n```\n\n## Quick Start (New Project)\n\n```bash\ncd /path/to/project\nvault-init\nvault-ai-context\nvault-doctor\n```\n\n## Enable Skills (Pack-first)\n\n```bash\ncd /path/to/project\nvault-ext enable laravel\nvault-ext enable skills\nvault-skills set backend-expert\nvault-skills sync\n```\n\nUseful checks:\n\n```bash\ncat .ai/extensions/lock.json\ncat .ai/skills/ACTIVE_SKILLS.md\n```\n\n## Daily Workflow\n\n```bash\n# Refresh context\nvault-ai-context\n\n# Work on a task\nvault-task \"Implement feature X\"\n\n# Validate health\nvault-doctor --strict\n```\n\n## Normalize Projects from \u003c= 4.x to 5.x\n\nUse this for existing projects that were on legacy/fallback behavior.\n\n### Step 1: Update core to v5\n\n```bash\ncd ~/.ai-shadow-vault\ngit fetch --tags\ngit checkout v5.0.0\nsource ~/.zshrc\n```\n\n### Step 2: Re-initialize project state\n\n```bash\ncd /path/to/project\nvault-init --non-interactive\n```\n\n### Step 3: Enable required pack + skills workflow\n\n```bash\nvault-ext enable laravel\nvault-ext enable skills\n```\n\n### Step 4: Re-apply active skills\n\n```bash\n# Example\nvault-skills set backend-expert\nvault-skills sync\n```\n\n### Step 5: Validate final state\n\n```bash\nvault-ai-context\nvault-doctor --strict\n```\n\nIf you get `ASV-HARD-MIGRATION-001`, install/enable the required pack and re-run `vault-skills set ...`.\n\n## Command Guide (What Each One Does)\n\n### `vault-init`\n\nInitializes or normalizes `.ai` structure and managed links/files for the current project.\n\nAfter every run, `vault-init` prints package suggestions when optional but recommended packages are missing from `composer.json`:\n\n- **Pest detected, `pao` not installed** → suggests `composer require nunomaduro/pao:0.x-dev --dev`\n- **Laravel detected, `laravel/boost` not installed** → suggests `composer require laravel/boost --dev`\n\nThe suggested command automatically uses the correct PHP binary (Herd → Sail → global composer).\n\nMain options:\n- `--optimize`: runs optimize flow (detect -\u003e plan -\u003e apply)\n- `--interactive`: enables prompts/confirmations\n- `--non-interactive`: default safe automation mode\n- `--dry-run`: preview mode for optimize flow\n- `--yes`: auto-accept prompts\n- `--force-config`: compatibility alias (deprecated) for `--optimize --interactive`\n- `--herd`: compatibility flag forwarded to configurator\n- `--use-gemini` / `--no-use-gemini`: compatibility flags (tooling remains optional)\n- `--enable-workflow` / `--disable-workflow`: compatibility flags (deprecated behavior notice)\n\n### `vault-update`\n\nUpdates local installation (`~/.ai-shadow-vault`) from `origin/main` and refreshes the current project.\n\nWhat it runs after update (or when already up-to-date):\n- `vault-init --non-interactive`\n- `vault-ai-context`\n- `vault-ext run-hook post-update`\n\n### `vault-ai-context`\n\nRegenerates `.ai/context/agent-context.md` with compact working-state continuity:\n- current focus\n- active branch\n- active plans\n- blockers/risks\n- active skills\n\n### `vault-task`\n\nCreates/manages `.ai/context/current-task.md` in canonical format.\n\nSubcommands:\n- `new [--mode plan|execute]`: interactive task creation\n- `quick \"\u003cgoal\u003e\" [--mode plan|execute]`: fast task seed from one line\n- `compile [--stdin|--input \"\u003ctext\u003e\"|--file \u003cpath\u003e] [--mode plan|execute] [--output-lang en|pt|auto] [--enrich conservative|repo-aware] [--format markdown|json] [--apply]`: compiles free text into structured task\n- `show`: prints current task file\n- `mode [plan|execute]`: get/set current mode frontmatter\n- `done`: archives state via `vault-ai-save`\n- `clear`: resets task to template\n- `archive`: same archival behavior as `done`\n\n### `vault-doctor`\n\nHealth check and normalization command for `.ai` structure/rules/contracts.\n\nMain options:\n- `--fix`: apply safe automatic fixes\n- `--fix-strict`: apply strict fixes (implies `--fix`)\n- `--strict`: fail on warnings/errors for stricter CI-like checks\n- `--json`: machine-readable output\n- `--interactive`: guided fix flow (cannot be combined with `--json` or `--fix*`)\n- `--check \u003cname\u003e`: run specific checks only (can repeat)\n- `--explain \u003ccode\u003e`: explain a diagnostic code (example: `D003`)\n\n### `vault-ext`\n\nProject extension/pack manager.\n\nSubcommands:\n- `list`: show available extensions\n- `info \u003cextension\u003e`: show metadata/source/kind\n- `status`: show enabled extensions in current project\n- `enable \u003cextension...\u003e`: enable extension(s); installs official packs when needed\n- `disable \u003cextension...\u003e`: disable extension(s)\n- `sync [extension...]`: re-run sync hooks and refresh lockfile\n- `run-hook \u003chook\u003e`: run a hook across enabled extensions\n\n### `vault-skills`\n\nSkills workflow command (pack-first in v5).\n\nMain subcommands:\n- `status`: show active/available skills status\n- `list [--json] [--group \u003cid\u003e] [--source pack|all]`: list available skills (grouped; pack-first by default)\n- `suggest [--json|--plan]`: detect/suggest skills and pack hints (read-only; no state mutation)\n- `auto`: auto-enable high-confidence decisions; auto-enables required pack (`laravel`) for deterministic Laravel signals\n- `set \u003cskill...\u003e`: set active skills\n- `sync`: rebuild/sync generated active-skills artifacts\n- `explain \u003cskill-id\u003e`: short explanation of skill purpose\n- `legacy ...`: pass-through to legacy installer interface\n\n### `vault-pack validate \u003cpack-dir\u003e`\n\nValidates `pack.json` manifest schema for an external pack directory.\n\n### `vault-ai-save`\n\nArchives current task/plans into `.ai/archive`, resets active task, refreshes agent context, and updates docs index.\n\n### `vault-ai-resume`\n\nPrints a quick recap of current task, working-state context, and recent archive entries.\n\n### `vault-ai-stats`\n\nShows local vault statistics (size, docs/cache/plans/archive counts, estimated token footprint).\n\n### `cc` and `cx` (Shell aliases)\n\nAvailable after loading shell integration:\n\n```bash\nsource ~/.ai-shadow-vault/scripts/shell_integration.zsh\n```\n\n- `cc`: runs Claude bootstrap recap (`claude-start`)\n- `cx`: runs Codex bootstrap recap (`codex-start`)\n\n## Packs and Contract\n\nPacks are external repositories (for example, `ai-shadow-vault-laravel`) with a minimal `pack.json` contract.\n\nRequired manifest fields:\n\n- `name`\n- `version`\n- `description`\n- `core_api`\n- `capabilities`\n\nOptional catalog (for metadata-driven detection/listing):\n\n- `skills/catalog.json`\n\nReference:\n\n- `docs/pack-contract.md`\n\n## Troubleshooting\n\n### `ASV-COMPAT-001`\n\nPack `core_api` range is not compatible with your core version.\nUse a compatible pack release or update core.\n\n### `ASV-HARD-MIGRATION-001`\n\nRequested skill is no longer provided by core.\nEnable the required pack (usually `laravel`) and set the skill again.\n\n### `No .ai directory found`\n\nRun `vault-init` in the target project first.\n\n## OS Support\n\n- macOS\n- Linux (ZSH)\n\n## Summary\n\nAI Shadow Vault is the stable local foundation.\nPacks provide stack depth.\n\nCore is infrastructure.\nPacks are expertise.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiogocnunes%2Fai-shadow-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiogocnunes%2Fai-shadow-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiogocnunes%2Fai-shadow-vault/lists"}