@event4u/agent-config 2.0.0 → 2.2.0

package/docs/troubleshooting.md

@@ -30,11 +30,11 @@ If any of these are missing or empty, the installer either didn't run or
 was interrupted. Re-run it:
 
 ```bash
-php vendor/bin/install.php --verbose
-# or
 bash scripts/install --verbose
 # or, to regenerate everything (overwrites existing bridge files):
 bash scripts/install --force
+# or, for one-shot installs without a local node_modules tree:
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 ```
 
 ### Check 2: Does your agent actually read these directories?
@@ -61,44 +61,34 @@ version explicitly and reinstall the plugin.
 
 ---
 
-## `composer require` / `npm install` runs, but no files were created
+## Installer ran but no files appeared
 
-Several security-conscious setups disable post-install hooks:
+The v2 distribution does **not** ship a `postinstall` hook — installing
+`@event4u/agent-config` via `npm install -g` only puts the `agent-config`
+binary on `$PATH`; it does not seed any project files. Run the
+orchestrator explicitly inside the project root:
 
 ```bash
-composer config allow-plugins.false
-# or in ~/.npmrc:
-ignore-scripts=true
-```
-
-In that case, the post-install hook never runs. Execute the installer
-manually:
+# One-shot, no local checkout required (recommended)
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 
-```bash
-php vendor/bin/install.php          # for Composer
-# or for npm — invoke the orchestrator directly:
-bash node_modules/@event4u/agent-config/scripts/install
+# When the global CLI is installed
+agent-config install --tools=claude-code,cursor
 ```
 
-The [`scripts/postinstall.sh`](../scripts/postinstall.sh) wrapper prints a
-loud error block when the underlying installer fails, so if you saw no
-output at all, scripts are likely disabled on your side.
-
 ---
 
-## Broken symlinks after `composer update` / `npm update`
+## Broken symlinks after upgrading the package
 
 When the package version changes, symlinks that pointed to the old
-vendor path may break. Re-run the installer — it is idempotent:
+package path may break. Re-run the installer — it is idempotent:
 
 ```bash
-php vendor/bin/install.php
-# or
-bash scripts/install
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 ```
 
 The installer replaces stale symlinks with fresh ones pointing at the
-current vendor path.
+current package path.
 
 ---
 
@@ -108,8 +98,8 @@ Native Windows is not a first-class target. The installer relies on Bash
 and Unix-style symlinks. Recommended setup:
 
 1. **WSL2** (preferred): install Ubuntu or a distribution of your choice,
-   clone the project inside the WSL filesystem, and run `composer
-   install` / `npm install` from WSL.
+   clone the project inside the WSL filesystem, and run
+   `npx @event4u/create-agent-config init` from WSL.
 2. **Git Bash**: works for the basic install, but symlinks require
    Developer Mode (Windows 10 1703+) or admin privileges. Without either,
    Git Bash falls back to copies, which means updates will not propagate
@@ -142,15 +132,13 @@ There is no dedicated uninstall command yet. Remove the package and
 clean up manually:
 
 ```bash
-# 1. Remove the dependency
-composer remove event4u/agent-config
-# or
+# 1. Remove the dependency (skip when installed via npx / -g)
 npm uninstall @event4u/agent-config
 
 # 2. Remove generated content from the project
 rm -rf .augment .claude .cursor .clinerules .windsurfrules GEMINI.md
 rm -f .agent-settings .agent-settings.yml .agent-settings.backup.key-value
-rm -f .github/copilot-instructions.md
+rm -f .github/copilot-instructions.md agent-config
 # Remove the "# event4u/agent-config" block from .gitignore manually
 ```
 
@@ -163,5 +151,5 @@ Keep `AGENTS.md` if you customized it — it is yours, not the package's.
 Open an [issue](https://github.com/event4u-app/agent-config/issues) with:
 
 - your OS and shell,
-- PHP / Node / Python versions,
+- Node / Python versions,
 - full output of `bash scripts/install --verbose --dry-run`.

package/llms.txt

@@ -6,6 +6,7 @@ Machine-readable index of all skills in this package. Each line:
 Source: .agent-src/skills/<name>/SKILL.md
 Catalog: docs/skills-catalog.md
 
+accessibility-auditor: Use when reviewing UI for accessibility — WCAG 2.2 AA, keyboard nav, focus, ARIA, contrast, screen-reader semantics — even on 'is this a11y-OK?' or 'mach das barrierefrei'.
 adr-create: Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'.
 adversarial-review: ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback.
 agent-docs-writing: Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure.
@@ -16,6 +17,7 @@ analysis-skill-router: Use when picking which analysis or project-analysis-* ski
 api-design: Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design.
 api-endpoint: Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs.
 api-testing: Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing.
+architecture-review-lens: Use when a diff may break system boundaries, dependency direction, or cross-service contracts — fifth judge dispatched by /review-changes alongside the four standard judges.
 artisan-commands: Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling.
 async-python-patterns: Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized.
 authz-review: Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows.
@@ -28,16 +30,19 @@ code-refactoring: Use when the user says "refactor this", "rename class", or "mo
 code-review: Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
 command-routing: Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns.
 command-writing: Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'.
+competitive-positioning: Use when comparing this package to a peer / competitor — ours-vs-theirs verdict table, axis selection, adoption queue. Triggers on 'how do we compare to X', 'should we adopt their pattern'.
 composer-packages: Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'.
 context-authoring: Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel.
 context-document: Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation.
 conventional-commits-writing: Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits.
 copilot-agents-optimization: Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience.
 copilot-config: Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'.
+customer-research: Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'.
 dashboard-design: Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling.
 data-flow-mapper: Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line.
 database: Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'.
 dcf-modeling: Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'.
+decision-record: Use when locking a trade-off, structuring an ADR draft, or wiring supersession chains — frames options · trade-offs · consequences before the file is written by `adr-create`.
 deep-reading-analyst: Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary.
 defense-in-depth: Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one.
 dependency-upgrade: Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification.
@@ -45,6 +50,7 @@ description-assist: Use when polishing a skill/rule/command/guideline frontmatte
 design-review: Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more.
 devcontainer: Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'.
 developer-like-execution: Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it.
+discovery-interview: Use when running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'.
 docker: Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'.
 dto-creator: Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping.
 eloquent: Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions.
@@ -56,11 +62,13 @@ feature-planning: Use when the user says "plan a feature", "brainstorm", "explor
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
 flux: Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives.
+form-handler: Use when designing or reviewing a form — validation timing, error display, submission lifecycle, optimistic UI, dirty/pristine state, idempotency — even on 'why does submit double-fire?'.
 funnel-analysis: Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven.
 git-workflow: Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git.
 github-ci: Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'.
 grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana.
 guideline-writing: Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'.
+incident-commander: Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'.
 jira-integration: Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
 jobs-events: Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling.
 judge-bug-hunter: Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'.
@@ -77,15 +85,19 @@ laravel-pulse: Use when setting up Laravel Pulse — real-time dashboard, built-
 laravel-reverb: Use when configuring Laravel Reverb — the first-party WebSocket server with Pusher protocol compatibility, horizontal scaling, and Pulse monitoring.
 laravel-scheduling: Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling.
 laravel-validation: Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it.
+launch-readiness: Use before merging a release-shaped PR — pre-merge checklist, rollout plan, rollback criteria, ops handoff. Triggers on 'ready to ship', 'launch checklist', 'rollout plan for X'.
 learning-to-rule-or-skill: Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work.
 lint-skills: Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata.
 livewire: Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation.
+livewire-architect: Use when shaping a Livewire component before code — full-page vs partial, parent/child split, event flow, state-vs-props boundary, hydration cost — even on 'add this Livewire component'.
 logging-monitoring: Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers.
 markitdown: Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'.
 mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
 mcp-builder: Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness.
 md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.
+memory-consolidation: Use when consolidating session signals into curated memory — four-phase loop ORIENT → GATHER → CONSOLIDATE → PRUNE. Triggers on 'mine my sessions', 'consolidate memory', 'review intake signals'.
 merge-conflicts: Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow.
+migration-architect: Use when shaping a non-trivial migration — rollout phases, dual-write windows, cutover sequencing, deprecation cycles — hands off to `migration-creator` for DDL once locked.
 migration-creator: Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness.
 mobile-e2e-strategy: Use when picking a mobile E2E framework — Detox / Appium / Maestro / XCUITest / Espresso — or planning iOS Simulator / Android Emulator coverage in CI for RN, Expo, or native apps.
 module-management: Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions.
@@ -100,7 +112,9 @@ pest-testing: Use when writing, generating, or improving Pest tests for Laravel
 php-coder: Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts.
 php-debugging: Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'.
 php-service: Use when the user says 'create service', 'new service class', or needs a PHP service following SOLID principles with proper DI and repository usage.
+playwright-architect: Use when shaping a Playwright suite — locator strategy, Page Object boundaries, fixture composition, flake-prevention architecture, CI-vs-local split — even on 'design our E2E tests'.
 playwright-testing: Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns.
+po-discovery: Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'.
 project-analysis-core: Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research.
 project-analysis-hypothesis-driven: Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'.
 project-analysis-laravel: Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns.
@@ -122,10 +136,12 @@ readme-writing-package: Use when creating or rewriting a README for a reusable p
 receiving-code-review: Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'.
 "refine-prompt": Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'.
 "refine-ticket": Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt.
+release-comms: Use when turning a shipped changelog into a release narrative — value-not-feature framing, audience-segmented surfaces, one source of truth. Triggers on 'announce the release', 'write changelog post'.
 repomix-packer: Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI.
 requesting-code-review: Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'.
 review-routing: Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML.
 rice-prioritization: Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort.
+risk-officer: Use when surfacing and prioritising risk before commit — blast-radius framing, mitigations, residual-risk verdict — even if the user just says 'what could go wrong here?'.
 roadmap-management: Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking.
 roadmap-writing: Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'.
 rtk-output-filtering: Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns.
@@ -141,8 +157,11 @@ skill-management: Use when compressing, decompressing, refactoring, or improving
 skill-reviewer: Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations.
 skill-writing: Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'.
 sql-writing: Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL.
-subagent-orchestration: Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml.
+stakeholder-tradeoff: Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'.
+subagent-orchestration: Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml.
 systematic-debugging: Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'.
+tailwind-engineer: Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'.
+tech-debt-tracker: Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'.
 technical-specification: Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure.
 terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
 terragrunt: Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt.
@@ -152,10 +171,12 @@ testing-anti-patterns: Use BEFORE writing or changing tests, adding mocks, or pu
 threat-modeling: Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation.
 token-optimizer: Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action.
 traefik: Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing.
+ui-component-architect: Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'.
 unit-economics-modeling: Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses.
 universal-project-analysis: ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills.
 upstream-contribute: Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package.
 using-git-worktrees: Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'.
 "validate-feature-fit": Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit
 verify-completion-evidence: Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs.
+voc-extract: Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'.
 websocket: Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.0.0",
+    "version": "2.2.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_export.py

@@ -0,0 +1,157 @@
+"""``agent-config export`` — eject a tool's canonical content into the project.
+
+Phase 1.5 of road-to-global-first-install.md (ADR-007 D3). Replaces the
+rejected symlink-bridge subcommand: writes a real file with the resolved
+content for a named tool into a user-chosen path so it can be committed,
+shared with the team, or customized in place. Idempotent by default;
+``--force`` overrides content drift. No canonical-path defaults.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+
+from scripts.install import (
+    AIDER_MARKER,
+    CLAUDE_DESKTOP_MARKER,
+    CODEX_MARKER,
+    CONTINUE_MARKER,
+    JETBRAINS_MARKER,
+    KILOCODE_MARKER,
+    KIRO_MARKER,
+    ROOCODE_MARKER,
+    ZED_MARKER,
+)
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+TEMPLATES_DIR = PACKAGE_ROOT / ".agent-src" / "templates"
+
+
+def _from_template(rel: str) -> Callable[[], str]:
+    def _read() -> str:
+        path = TEMPLATES_DIR / rel
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"template missing from package: {path} "
+                f"(reinstall @event4u/agent-config or report a bug)"
+            )
+        return path.read_text(encoding="utf-8")
+    return _read
+
+
+def _from_constant(value: str) -> Callable[[], str]:
+    def _read() -> str:
+        return value
+    return _read
+
+
+# tool_id → (description, content_provider).
+EXPORT_REGISTRY: "dict[str, tuple[str, Callable[[], str]]]" = {
+    "roocode": ("Roo Code marker (.roo/rules/agent-config.md body)",
+                _from_constant(ROOCODE_MARKER)),
+    "claude-desktop": ("Claude Desktop marker (informational, global-scope tool)",
+                       _from_constant(CLAUDE_DESKTOP_MARKER)),
+    "aider": ("Aider marker (manual `read:` wiring documented inline)",
+              _from_constant(AIDER_MARKER)),
+    "codex": ("Codex CLI marker (informational — AGENTS.md is canonical)",
+              _from_constant(CODEX_MARKER)),
+    "continue": ("Continue.dev marker (.continue/rules/agent-config.md body)",
+                 _from_constant(CONTINUE_MARKER)),
+    "kilocode": ("Kilo Code marker (.kilocode/rules/agent-config.md body)",
+                 _from_constant(KILOCODE_MARKER)),
+    "zed": ("Zed marker (informational — .rules at repo root is canonical)",
+            _from_constant(ZED_MARKER)),
+    "jetbrains": ("JetBrains AI Assistant marker (.jetbrains/agent-config.md body)",
+                  _from_constant(JETBRAINS_MARKER)),
+    "kiro": ("Kiro marker (.kiro/steering/agent-config.md body)",
+             _from_constant(KIRO_MARKER)),
+    "agents-md": ("AGENTS.md template (Thin-Root entry point — consumer scaffold)",
+                  _from_template("AGENTS.md")),
+    "copilot-instructions": ("GitHub Copilot Code Review instructions template",
+                             _from_template("copilot-instructions.md")),
+}
+
+
+def _list_tools(out) -> int:
+    print("Available tools for `agent-config export --tool <id>`:", file=out)
+    width = max(len(t) for t in EXPORT_REGISTRY) + 2
+    for tool_id, (desc, _) in sorted(EXPORT_REGISTRY.items()):
+        print(f"  {tool_id:<{width}}{desc}", file=out)
+    return 0
+
+
+def _hash(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _rel(path: Path) -> Path:
+    try:
+        return path.relative_to(Path.cwd())
+    except ValueError:
+        return path
+
+
+def _write(output: Path, content: str, *, force: bool, out, err) -> int:
+    if output.exists():
+        existing = output.read_text(encoding="utf-8")
+        if _hash(existing) == _hash(content):
+            print(f"ℹ️  {_rel(output)} already exported (content matches).", file=out)
+            return 0
+        if not force:
+            print(
+                f"❌  refusing to overwrite {output} — content differs. "
+                f"Pass --force to replace.",
+                file=err,
+            )
+            return 1
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(content, encoding="utf-8")
+    print(f"✅  exported to {_rel(output)}", file=out)
+    return 0
+
+
+def main(argv: Optional[list[str]] = None, *, out=sys.stdout, err=sys.stderr) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config export",
+        description="Eject a tool's resolved content into a user-chosen path.",
+    )
+    parser.add_argument("--tool", metavar="ID",
+                        help="Tool to export (see --list for the catalog).")
+    parser.add_argument("--output", metavar="PATH",
+                        help="Destination path (relative to CWD).")
+    parser.add_argument("--force", action="store_true",
+                        help="Overwrite an existing file with non-matching content.")
+    parser.add_argument("--list", action="store_true",
+                        help="Print supported tool IDs with descriptions and exit.")
+    args = parser.parse_args(argv)
+
+    if args.list:
+        return _list_tools(out)
+    if not args.tool:
+        print("❌  --tool is required (see --list for the catalog).", file=err)
+        return 2
+    if not args.output:
+        print("❌  --output is required (no canonical-path defaults).", file=err)
+        return 2
+
+    entry = EXPORT_REGISTRY.get(args.tool)
+    if entry is None:
+        print(f"❌  unknown tool: {args.tool} (see --list)", file=err)
+        return 2
+
+    _, provider = entry
+    try:
+        content = provider()
+    except FileNotFoundError as exc:
+        print(f"❌  {exc}", file=err)
+        return 1
+
+    output = Path(args.output).expanduser().resolve()
+    return _write(output, content, force=args.force, out=out, err=err)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/_cli/cmd_sync.py

@@ -0,0 +1,162 @@
+"""``agent-config sync`` — replay the installed-tools manifest (ADR-008).
+
+Phase 3.3 of road-to-global-first-install.md. Reads
+``agents/installed-tools.lock``, then re-runs the bridge install for every
+tool whose ``bridge_marker`` is missing on disk. Tools whose marker already
+exists are skipped — the typical clone-and-sync flow is therefore idempotent
+on the second invocation.
+
+Sync never edits the manifest itself; ``init`` is the only writer. Sync only
+calls the installer with ``--scope`` / ``--tools`` derived from the manifest
+entries, so the manifest is the single source of truth.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from scripts._lib import installed_tools
+from scripts.install import main as install_main
+
+
+def _marker_exists(project_root: Path, bridge_marker: str, scope: str) -> bool:
+    if not bridge_marker:
+        return True  # substrate-only entries (rare); treat as present
+    if scope == "global":
+        target = Path(bridge_marker).expanduser()
+    else:
+        # Project-scope: relative to the project root unless absolute.
+        candidate = Path(bridge_marker)
+        target = candidate if candidate.is_absolute() else (project_root / candidate)
+    return target.exists()
+
+
+def _group_by_scope(
+    entries: Iterable[dict],
+    project_root: Path,
+) -> tuple[dict[str, list[str]], list[tuple[str, str]]]:
+    """Return ({scope: [tool_names]}, [(name, marker_path)]) for missing tools.
+
+    The second list is the human-readable summary of what will be replayed.
+    """
+    missing: dict[str, list[str]] = {"project": [], "global": []}
+    surfaced: list[tuple[str, str]] = []
+    for entry in entries:
+        name = str(entry.get("name", "")).strip()
+        scope = str(entry.get("scope", "")).strip()
+        bridge_marker = str(entry.get("bridge_marker", "")).strip()
+        if not name or scope not in ("project", "global"):
+            continue
+        if _marker_exists(project_root, bridge_marker, scope):
+            continue
+        missing[scope].append(name)
+        surfaced.append((name, bridge_marker))
+    return missing, surfaced
+
+
+def _run_install(scope: str, tools: list[str], project_root: Path, *, force: bool, dry_run: bool) -> int:
+    if not tools:
+        return 0
+    argv = [f"--scope={scope}", f"--tools={','.join(sorted(set(tools)))}"]
+    if scope == "project":
+        argv += [f"--project={project_root}", "--no-smoke"]
+    if force:
+        argv.append("--force")
+    if dry_run:
+        argv.append("--skip-bridges")
+    return install_main(argv)
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config sync",
+        description=(
+            "Replay agents/installed-tools.lock — re-installs any tool whose "
+            "bridge marker is missing locally. Idempotent."
+        ),
+    )
+    parser.add_argument(
+        "--project",
+        default=None,
+        help="Override the project root (defaults to PROJECT_ROOT or cwd).",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the planned replay set without touching bridges.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Forwarded to the installer (overwrites existing bridge files).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-essential output.",
+    )
+    return parser.parse_args(argv)
+
+
+def _emit(quiet: bool, msg: str) -> None:
+    if not quiet:
+        print(msg)
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse(argv)
+    project_root = Path(
+        opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
+    ).resolve()
+    manifest = installed_tools.manifest_path(project_root)
+    data = installed_tools.read_manifest(manifest)
+
+    if data is None:
+        _emit(opts.quiet, f"❌  No manifest found at {manifest}")
+        _emit(opts.quiet, "    Run `./agent-config init --tools=<id>` to create one.")
+        return 1
+
+    entries = list(data.get("tools") or [])
+    if not entries:
+        _emit(opts.quiet, f"ℹ️  Manifest is empty: {manifest}")
+        return 0
+
+    missing, surfaced = _group_by_scope(entries, project_root)
+    total_missing = sum(len(v) for v in missing.values())
+    total_present = len(entries) - total_missing
+
+    _emit(opts.quiet, f"Manifest:  {manifest}")
+    _emit(opts.quiet, f"Tools:     {len(entries)} listed, {total_present} present, {total_missing} missing")
+    if total_missing == 0:
+        _emit(opts.quiet, "✅  All bridges already installed. Nothing to do.")
+        return 0
+
+    for name, marker in surfaced:
+        _emit(opts.quiet, f"  • {name:<15} → {marker} (missing)")
+
+    if opts.dry_run:
+        _emit(opts.quiet, "")
+        _emit(opts.quiet, "Dry-run: no bridges written.")
+        return 0
+
+    _emit(opts.quiet, "")
+    for scope in ("project", "global"):
+        tools = missing[scope]
+        if not tools:
+            continue
+        _emit(opts.quiet, f"Replaying scope={scope}: {', '.join(sorted(tools))}")
+        rc = _run_install(scope, tools, project_root, force=opts.force, dry_run=False)
+        if rc != 0:
+            _emit(opts.quiet, f"❌  Installer failed for scope={scope} (rc={rc}); aborting.")
+            return rc
+
+    _emit(opts.quiet, "")
+    _emit(opts.quiet, "✅  Sync complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/_cli/cmd_update.py

@@ -36,7 +36,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from scripts._lib import update_check
+from scripts._lib import installed_lock, update_check
 from scripts._lib.agent_settings import (
     DEFAULT_PROJECT_FILE,
     _resolve_cascade_paths,
@@ -205,9 +205,31 @@ def main(
 
     cache_warmer(latest)
     _refresh_state(latest, latest, state_path)
+    _refresh_global_lockfile(latest, out=out)
     return 0
 
 
+def _refresh_global_lockfile(version: str, *, out=sys.stdout) -> None:
+    """Update ``~/.config/agent-config/installed.lock`` if it exists.
+
+    Phase 1.6 — the lockfile is only present when the user has run a
+    global install; we never create one here, but we keep it in lockstep
+    when ``update`` flips the pin. Atomic write goes through
+    ``installed_lock.write_lockfile``.
+    """
+    lock_path = installed_lock.lockfile_path()
+    existing = installed_lock.read_lockfile(path=lock_path)
+    if existing is None:
+        return
+    recorded = existing.get("agent_config_version")
+    tools = list(existing.get("tools", []))
+    if recorded == version:
+        print(f"ℹ️  {lock_path} already records {version}.", file=out)
+        return
+    installed_lock.write_lockfile(version, tools, path=lock_path)
+    print(f"✅  Refreshed global lockfile at {lock_path}.", file=out)
+
+
 def _detect_installed_version() -> str:
     """Read ``version`` from the package's own ``package.json``."""
     pkg_json = Path(__file__).resolve().parents[2] / "package.json"