Merge pull request #56 from sampleXbro/develop

Develop

Author: sampleXbro

.agentsmesh/.lock

@@ -1,9 +1,9 @@
 # Auto-generated. DO NOT EDIT MANUALLY.
 # Tracks the state of all config files for team conflict resolution.
 
-generated_at: 2026-05-08T14:56:34.513Z
+generated_at: 2026-05-09T14:39:23.798Z
 generated_by: serhii
-lib_version: 0.15.0
+lib_version: 0.16.0
 checksums:
   agents/code-debugger.md: sha256:33452bf839256a119a602cd10d085bff3cdb8f537ded76e60053bb9d8e5d33bc
   agents/code-documenter.md: sha256:89b4ebd27718bcd50a7283c95ea1ff9cad153b1112cf695f9f1fc22d90ec85ec

.aider/skills/add-agent-target/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: add-agent-target
+description: Use when adding support for a new AI agent target to agentsmesh. Covers official format research, canonical mapping, importer/generator/linter work, realistic fixtures, unit/integration/e2e coverage, matrix/docs updates, and final verification. Includes both project and global mode from day one.
+---
+
+## Purpose
+
+# Add Agent Target
+
+Use this skill when the task is to add a brand-new supported agent target to this repository (built-in) or as an external plugin package.
+
+**Primary reference**: `docs/add-new-target-playbook.md` is the step-by-step workflow (phases 1–9, file templates, verification gates). Open it first and follow it. This skill file is the contract — the non-negotiable rules, touchpoints, and completion bar. The playbook is how; this file is what and why.
+
+**Companion skill**: `add-global-mode-target` — use only when extending global-mode support into an existing target that was built before global was a first-class contract. For new targets, global mode is part of this skill (scaffold wires it automatically).
+
+## When To Use
+
+- The task is to add a tool not currently in `src/targets/catalog/target-ids.ts`
+- Scope covers both `project` and `global` modes unless the target has no meaningful global surface
+- Delivery is either built-in (in this repo) or external plugin (standalone npm package)
+
+## Do Not Use This Skill For
+
+- Extending global-mode coverage on an existing target — use `add-global-mode-target`
+- Changing capability levels for an existing target — update the target's descriptor directly
+- Plugin feature work that doesn't add a new target id
+
+## Non-Negotiable Rules
+
+### MUST
+
+- Search the internet for the target's current official file structure, config files, and example content before changing code.
+- Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
+- Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like `codex-cli` with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
+- Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
+- When a feature is `none` but `skills` is `native` or `embedded`, evaluate whether `supportsConversion` should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via `supportsConversion: { commands: true, agents: true }` and registered in `src/config/core/conversions.ts` with `DEFAULT_*_TO_SKILLS`. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
+- Start from `agentsmesh target scaffold <id>` when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
+- Write failing tests first for every new behavior. Do not implement first and backfill later.
+- Add unit, integration, and e2e coverage for the complete import and generate flow, including global scope when applicable.
+- Add rich and realistic fixtures for the new target. Fixtures must resemble real projects, not toy placeholders.
+- Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
+- Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
+- Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
+- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass.
+- Update init detection and import empty-state messaging for the new target when native files exist.
+- Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
+- Preserve the canonical `.agentsmesh/` contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.
+- Ensure every internal file link or reference inside generated or imported Markdown artifacts is convertible through the shared reference-rewrite pipeline, just like the existing targets. Do not ship a new target unless canonical `.agentsmesh/` references round-trip cleanly across that target's Markdown surfaces.
+- Run the full verification stack, including the packaging gates (`pnpm attw`, `pnpm publint`, `pnpm consumer-smoke`), before claiming completion.
+- Run the `post-feature-qa` skill before marking the task done.
+
+### MUST NOT
+
+- Do not infer the target format from old fixtures, README text, or memory alone.
+- Do not add placeholder fixtures with `SYNTHETIC` markers or obviously fake content.
+- Do not add shallow smoke tests as a substitute for feature coverage.
+- Do not silently skip unsupported features; document and test the chosen behavior.
+- Do not leave commands, schema enums, init detection, matrix output, or docs partially updated.
+- Do not hardcode target-specific branches in shared code when a descriptor field can carry the behavior.
+
+## Workflow (detailed in `docs/add-new-target-playbook.md`)
+
+1. **Research** — §1 of the playbook. Answer every research-checklist item from primary sources before writing code.
+2. **Scaffold** — §2 of the playbook. Run `pnpm exec agentsmesh target scaffold <id>`, then register the id in the three catalog files listed there.
+3. **Constants and capabilities** — §3. Fill in paths and capability levels for both project and global scope.
+4. **Conversion eligibility** — For each feature marked `none` in capabilities, check if the target supports skills (`native` or `embedded`). If so, add `supportsConversion` to the descriptor for those features, register defaults in `src/config/core/conversions.ts`, and omit lint warnings for those features (they become `embedded` via skill projection). Only emit lint warnings for features that are truly dropped with no fallback.
+5. **Tests first** — §4. Add realistic fixtures under `tests/e2e/fixtures/<id>-project/` and write failing unit/integration/e2e tests.
+5. **Implement generators, importers, and reference maps** — §5. Feature-by-feature, using existing targets as reference implementations.
+6. **Global mode** — §6. Fill in `descriptor.global`, `rewriteGeneratedPath`, and any `skillMirror` or `sharedArtifacts` needs.
+7. **Plugin packaging** — §7. Only if shipping as an external plugin rather than a built-in.
+8. **Matrix and docs** — §8. Run `pnpm schemas:generate && pnpm matrix:generate` and update `website/src/content/docs/reference/supported-tools.mdx`.
+9. **Verification** — §9. Run the full stack (see below). All must pass.
+
+Refer to `./references/target-addition-checklist.md` for the concrete audit list of touchpoints, tests, fixtures, and edge cases.
+
+## Required Verification
+
+Before claiming completion, every command must pass:
+
+- `pnpm typecheck`
+- `pnpm lint`
+- `pnpm test`
+- `pnpm test:e2e`
+- `pnpm matrix:verify`
+- `pnpm publint`
+- `pnpm attw`
+- `pnpm consumer-smoke`
+
+If a narrower command is useful during iteration, run it first, but do not skip the full stack at the end.
+
+## Completion Standard
+
+The task is not done until all of the following are true:
+
+- The target appears in `agentsmesh matrix` CLI output and passes `pnpm matrix:verify`.
+- Import and generate behavior are both covered for every supported feature, in both project and global scope where applicable.
+- Unsupported or lossy features are documented in `website/src/content/docs/reference/supported-tools.mdx` and tested.
+- Fixtures under `tests/e2e/fixtures/<id>-project/` are rich enough to exercise real parsing branches (rules, skills, MCP, hooks, ignore as applicable).
+- Round-trip import → generate preserves content byte-for-byte where the format permits.
+- README matrix and website supported-tools page are in sync.
+- All verification commands listed above pass.
+- `post-feature-qa` skill has been applied and any gaps closed.

.aider/skills/add-agent-target/references/target-addition-checklist.md

@@ -0,0 +1,152 @@
+# Target Addition Checklist
+
+Concrete audit list for adding a built-in agent target. For the step-by-step workflow, see `docs/add-new-target-playbook.md`.
+
+## Research (non-skippable)
+
+Every item must have a primary-source link before coding starts:
+
+- Official docs URL for the tool
+- Exact product surface being implemented (CLI vs desktop vs chat — often different config systems)
+- Project-scope config directory and root-instruction file
+- Global-scope config directory and root-instruction file
+- File formats for each supported feature (Markdown + frontmatter, YAML, TOML, JSON)
+- Frontmatter keys and schema per feature
+- Legacy or fallback paths still in use
+- Capability map — for each canonical feature, one of: `native`, `embedded`, `partial`, `none`
+- Conversion eligibility — for each `none` feature, can it be projected as a skill? (see below)
+- MCP scope (project file, user-home config, app-managed connector, unsupported)
+
+## Code Touchpoints
+
+Registration (must edit these three files for a built-in target):
+
+- `src/targets/catalog/target-ids.ts` — add the new id to `TARGET_IDS`
+- `src/targets/catalog/builtin-targets.ts` — import the descriptor and add to `BUILTIN_TARGETS`
+- `src/core/reference/import-maps/index.ts` — re-export the new target's import-paths helper
+
+Target implementation (scaffold produces these; fill in):
+
+- `src/targets/<id>/constants.ts` — project and global path constants
+- `src/targets/<id>/index.ts` — the `TargetDescriptor` (capabilities, layouts, detection paths)
+- `src/targets/<id>/generator.ts` — feature generators (`generateRules` minimum)
+- `src/targets/<id>/importer.ts` — `importFrom` implementation
+- `src/targets/<id>/linter.ts` — rule linter (often thin wrapper over shared `validateRules`)
+- `src/targets/<id>/lint.ts` — per-feature lint hooks (commands, mcp, permissions, hooks, ignore)
+- `src/core/reference/import-maps/<id>.ts` — canonical ↔ target reference path map
+
+Conversion eligibility (when `commands` or `agents` is `none` but `skills` is `native` or `embedded`):
+
+- `src/targets/<id>/index.ts` — add `supportsConversion: { commands: true, agents: true }` (only the features that are `none`)
+- `src/config/core/conversions.ts` — add the target to `DEFAULT_COMMANDS_TO_SKILLS` and/or `DEFAULT_AGENTS_TO_SKILLS` with `true`
+- Do NOT add lint warnings for converted features — they are projected as skills, not dropped
+- Only add lint warnings for features that are truly unsupported (no native support AND no skill fallback, e.g. hooks, permissions, MCP when project-only)
+
+Shared code to audit, not usually modify:
+
+- `src/config/core/schema.ts` — target id validation runs off `TARGET_IDS`, no edits needed
+- `src/cli/help-data.ts` — only if the target introduces new flags; avoid if possible
+- `src/core/matrix/data.ts` — auto-derived from descriptor capabilities, no edits needed
+- `src/core/generate/collision.ts` — only if declaring `sharedArtifacts`
+
+## Documentation Touchpoints
+
+- `README.md` — matrix tables update automatically via `pnpm matrix:generate`
+- `website/src/content/docs/reference/supported-tools.mdx` — single docs page for per-target detail (paths, native vs embedded, limitations). Update this manually.
+- `docs/prd-v2-complete.md` — only if the architecture contract changes
+- No other docs pages should need edits per repo rules
+
+## Unit Tests
+
+- `tests/unit/targets/<id>/generator.test.ts`
+- `tests/unit/targets/<id>/importer.test.ts`
+- `tests/unit/targets/<id>/global-layout.test.ts` (when the target supports global mode)
+- `tests/unit/targets/<id>/<feature>-helpers.test.ts` (only if the target has complex helpers)
+- Shared tests (`tests/unit/core/engine.test.ts`, `tests/unit/core/matrix/*.test.ts`) only when behavior there changes
+
+Assertions must be strict: exact paths, exact counts, exact referenced sets. No `some(...)`, no `toBeGreaterThan(0)` on lengths, no prefix-only matching.
+
+## Integration Tests
+
+- `tests/integration/generate.integration.test.ts` — when CLI generate wiring is affected
+- `tests/integration/import.integration.test.ts` — when CLI import wiring is affected
+- `tests/integration/init.integration.test.ts` — when init detection changes
+
+## E2E Tests
+
+- `tests/e2e/generate-capabilities.e2e.test.ts` — add a describe block for the new target
+- `tests/e2e/import-capabilities.e2e.test.ts` — add import round-trip cases
+- `tests/e2e/full-sync.e2e.test.ts` — when the target supports import
+- `tests/e2e/<id>-format-roundtrip.e2e.test.ts` — only for complex targets with non-trivial format handling (see `claude-code-format-roundtrip.e2e.test.ts` as reference)
+- Global coverage — add to existing global roundtrip suites rather than creating new isolated files
+
+## Fixture Requirements
+
+Create `tests/e2e/fixtures/<id>-project/` with realistic content:
+
+- Target's root instructions file (with real prose, not a placeholder)
+- Scoped rules or equivalent (with frontmatter, globs, trigger markers as applicable)
+- Commands or workflows if supported
+- Agents if supported
+- Skills with at least one supporting file (`references/`, `scripts/`, or `template.*`)
+- Settings, MCP, hooks, ignore files as applicable
+- Legacy/fallback variant in a separate fixture if the target has path precedence rules
+
+Reference fixtures for comparison:
+
+- `tests/e2e/fixtures/kiro-project/` — 10 files, rules + skills + MCP (mid-complexity)
+- `tests/e2e/fixtures/claude-code-project/` — 14 files, full feature set (high-complexity)
+
+## Edge Cases To Cover
+
+- Missing config produces the correct empty-state message from `emptyImportMessage`
+- Legacy path fallback (when the target has one)
+- Precedence when both legacy and current formats exist
+- Malformed JSON/TOML/frontmatter (importer must not crash)
+- Partial feature translation (document lossy behavior in tests)
+- Existing settings merge preservation (when generator writes into a shared settings file)
+- Rich skill directories with nested supporting files
+- `--targets <id>` filtering
+- Full round-trip import → generate when the target supports import
+- Global-scope variants for every project-scope test, when the target supports global
+
+## Global Mode (new targets must include from day one)
+
+- `descriptor.global` filled in with paths and managed outputs
+- `descriptor.global.rewriteGeneratedPath` transforms project paths to global
+- `descriptor.globalCapabilities` set only if different from project scope
+- `descriptor.globalDetectionPaths` populated
+- Optional: `descriptor.globalSupport.skillMirror` for targets that read skills from a mirror path
+- Optional: `descriptor.sharedArtifacts` when the target shares a global path with another target
+- Tests: `global-layout.test.ts` asserts descriptor shape; existing global roundtrip suites exercise the runtime behavior
+
+If the target genuinely has no global surface (e.g. a project-only tool), document the decision in `supported-tools.mdx` and omit `descriptor.global` entirely.
+
+## Plugin Path Alternative
+
+If the target is niche or the maintainer prefers independent release, ship as a plugin instead. See `docs/add-new-target-playbook.md` §7 for the standalone npm package layout. The descriptor contract is identical; only the packaging and registration differ.
+
+## Verification Gates
+
+Before marking complete, every command must exit 0:
+
+- `pnpm typecheck`
+- `pnpm lint`
+- `pnpm test`
+- `pnpm test:e2e`
+- `pnpm matrix:verify`
+- `pnpm publint`
+- `pnpm attw`
+- `pnpm consumer-smoke`
+
+## Review Questions
+
+- Did you search the internet first, using official docs only?
+- Did you start from `agentsmesh target scaffold <id>`, or did you hand-write the skeleton?
+- Did you write failing tests first?
+- Did you add rich fixtures instead of placeholders?
+- Did you register the id in all three catalog files (`target-ids.ts`, `builtin-targets.ts`, `import-maps/index.ts`)?
+- Did you include global mode, or document the decision to omit it?
+- Did you check conversion eligibility for `none` features — could commands/agents be projected as skills instead of dropped?
+- Did you update `supported-tools.mdx` with per-target detail?
+- Did every verification command pass?