diff --git a/.agents/rules/general.md b/.agents/rules/general.md index 8123eeb5..87e7de76 100644 --- a/.agents/rules/general.md +++ b/.agents/rules/general.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.agents/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.agents/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.agents/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.agents/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.agentsmesh/.lock b/.agentsmesh/.lock index be7e03ec..3d4f5ac3 100644 --- a/.agentsmesh/.lock +++ b/.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-03-30T12:15:20.515Z +generated_at: 2026-03-31T10:01:52.933Z generated_by: serhii -lib_version: 0.2.9 +lib_version: 0.2.10 checksums: agents/code-debugger.md: sha256:707132841c606f117c83491d53ce101be0117eb50abe2861bcf93bdd45a56daf agents/code-documenter.md: sha256:faa66b16d2e86578985e817d60e6705ae0e34a716c1f5c29411739a6d659fb96 @@ -16,11 +16,11 @@ checksums: commands/commit.md: sha256:3e6dcc5871ad157c36efe19c162b43cdc0d723a8695fb0d45c1f90cc28fa931c commands/review.md: sha256:ba3053410e7cc3271f41ba329056df07c6ccd2f07e2ed3dda601c56e46a77d54 commands/test.md: sha256:a60932b216ff9eb407c2b38e4459ac4b9606a3aed275f4af84a646eb6c2937e7 - hooks.yaml: sha256:1016bf9b001da63776022e928088cc4971a123e79e9bab959f04557acd58e3ee + hooks.yaml: sha256:9b2d2f11f9fe2bb7abd3b9dddc77df9ba9bda292aa5a6109c468b2dbff19ba2c ignore: sha256:9bd184903aee9e824fcd475e965103a8ef5efe5d5e98b0e7e275fb8017c4fc0e mcp.json: sha256:4269c04f9edf4142cde79d1e45f25958eaca54489cc19ec078eaba887d296018 permissions.yaml: sha256:9c22c5221457f6c165a5f135448f3f95fedb8c9339cb9f91998d844184501158 - rules/_root.md: sha256:e2a08a31514ef65656fe3a35299f9a8a4a95c50f502918807c7faecd2ca62540 + rules/_root.md: sha256:59aa3f817487ff1053f0718589c0b075b6f97a17b32435563ca30c9555a499aa rules/typescript.md: sha256:18f52143dfdd3e219a5c6d6c0feb7283fe74cce99458c46dafcd1c3620ad4fba skills/add-agent-target/SKILL.md: sha256:53a76c84b87f7735c53ac5f5e584e55122c09728a14406e7088ea93b5b183406 skills/add-agent-target/references/target-addition-checklist.md: sha256:66cd8f5ed4dd21b27e2bf4b34ae749ee301b28a208c83fecffa06748c2d2d61c diff --git a/.agentsmesh/hooks.yaml b/.agentsmesh/hooks.yaml index 2decafdb..f1b9375c 100644 --- a/.agentsmesh/hooks.yaml +++ b/.agentsmesh/hooks.yaml @@ -1,8 +1,9 @@ PreToolUse: - - matcher: Edit|Write + - matcher: Bash type: command - command: eslint --fix + command: "echo \"Running: $(jq -r '.tool_input.command' < /dev/stdin)\"" PostToolUse: - - matcher: Read - type: prompt - prompt: Review the file content for any security concerns + - matcher: Edit|Write + type: command + command: "jq -r '.tool_input.file_path' | xargs eslint --fix" + diff --git a/.agentsmesh/rules/_root.md b/.agentsmesh/rules/_root.md index 560c6c97..ffc9bf0d 100644 --- a/.agentsmesh/rules/_root.md +++ b/.agentsmesh/rules/_root.md @@ -6,87 +6,68 @@ root: true ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.agentsmesh/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.agentsmesh/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.agentsmesh/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.agentsmesh/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a7ba001f..2d8deb34 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.claude/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.claude/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.claude/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.claude/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.claude/settings.json b/.claude/settings.json index 2472ddb2..e8ed4327 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -12,22 +12,22 @@ "hooks": { "PreToolUse": [ { - "matcher": "Edit|Write", + "matcher": "Bash", "hooks": [ { "type": "command", - "command": "eslint --fix" + "command": "echo \"Running: $(jq -r '.tool_input.command' < /dev/stdin)\"" } ] } ], "PostToolUse": [ { - "matcher": "Read", + "matcher": "Edit|Write", "hooks": [ { - "type": "prompt", - "prompt": "Review the file content for any security concerns" + "type": "command", + "command": "jq -r '.tool_input.file_path' | xargs eslint --fix" } ] } diff --git a/.clinerules/hooks/posttooluse-0.sh b/.clinerules/hooks/posttooluse-0.sh index 07ddbb5d..69bbb4aa 100644 --- a/.clinerules/hooks/posttooluse-0.sh +++ b/.clinerules/hooks/posttooluse-0.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# agentsmesh-matcher: Read -# agentsmesh-command: Review the file content for any security concerns +# agentsmesh-matcher: Edit|Write +# agentsmesh-command: jq -r '.tool_input.file_path' | xargs eslint --fix set -e -Review the file content for any security concerns +jq -r '.tool_input.file_path' | xargs eslint --fix diff --git a/.clinerules/hooks/pretooluse-0.sh b/.clinerules/hooks/pretooluse-0.sh index ef1b966f..4796e58b 100644 --- a/.clinerules/hooks/pretooluse-0.sh +++ b/.clinerules/hooks/pretooluse-0.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# agentsmesh-matcher: Edit|Write -# agentsmesh-command: eslint --fix +# agentsmesh-matcher: Bash +# agentsmesh-command: echo "Running: $(jq -r '.tool_input.command' < /dev/stdin)" set -e -eslint --fix +echo "Running: $(jq -r '.tool_input.command' < /dev/stdin)" diff --git a/.continue/rules/general.md b/.continue/rules/general.md index 2208f119..47866b92 100644 --- a/.continue/rules/general.md +++ b/.continue/rules/general.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.continue/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.continue/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.continue/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.continue/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.cursor/hooks.json b/.cursor/hooks.json index 1bbc5844..a85de42d 100644 --- a/.cursor/hooks.json +++ b/.cursor/hooks.json @@ -3,22 +3,22 @@ "hooks": { "PreToolUse": [ { - "matcher": "Edit|Write", + "matcher": "Bash", "hooks": [ { "type": "command", - "command": "eslint --fix" + "command": "echo \"Running: $(jq -r '.tool_input.command' < /dev/stdin)\"" } ] } ], "PostToolUse": [ { - "matcher": "Read", + "matcher": "Edit|Write", "hooks": [ { - "type": "prompt", - "prompt": "Review the file content for any security concerns" + "type": "command", + "command": "jq -r '.tool_input.file_path' | xargs eslint --fix" } ] } diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc index 734e3d8c..2d5e4003 100644 --- a/.cursor/rules/general.mdc +++ b/.cursor/rules/general.mdc @@ -6,91 +6,72 @@ alwaysApply: true ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.cursor/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.cursor/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.cursor/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.cursor/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.gemini/settings.json b/.gemini/settings.json index 423f774d..cf94ee78 100644 --- a/.gemini/settings.json +++ b/.gemini/settings.json @@ -28,24 +28,24 @@ "hooks": { "BeforeTool": [ { - "matcher": "Edit|Write", + "matcher": "Bash", "hooks": [ { "name": "BeforeTool-1", "type": "command", - "command": "eslint --fix" + "command": "echo \"Running: $(jq -r '.tool_input.command' < /dev/stdin)\"" } ] } ], "AfterTool": [ { - "matcher": "Read", + "matcher": "Edit|Write", "hooks": [ { "name": "AfterTool-1", "type": "command", - "command": "Review the file content for any security concerns" + "command": "jq -r '.tool_input.file_path' | xargs eslint --fix" } ] } diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5fb49bf9..53035ea1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.github/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.github/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.github/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.github/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.github/hooks/agentsmesh.json b/.github/hooks/agentsmesh.json index 6f4c1a17..f591efdf 100644 --- a/.github/hooks/agentsmesh.json +++ b/.github/hooks/agentsmesh.json @@ -5,14 +5,14 @@ { "type": "command", "bash": "./scripts/pretooluse-0.sh", - "comment": "Matcher: Edit|Write" + "comment": "Matcher: Bash" } ], "postToolUse": [ { "type": "command", "bash": "./scripts/posttooluse-0.sh", - "comment": "Matcher: Read" + "comment": "Matcher: Edit|Write" } ] } diff --git a/.github/hooks/scripts/posttooluse-0.sh b/.github/hooks/scripts/posttooluse-0.sh index 45f4ad9f..b89924fa 100644 --- a/.github/hooks/scripts/posttooluse-0.sh +++ b/.github/hooks/scripts/posttooluse-0.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# agentsmesh-matcher: Read -# agentsmesh-command: Review the file content for any security concerns +# agentsmesh-matcher: Edit|Write +# agentsmesh-command: jq -r '.tool_input.file_path' | xargs eslint --fix set -e HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -Review the file content for any security concerns +jq -r '.tool_input.file_path' | xargs eslint --fix diff --git a/.github/hooks/scripts/pretooluse-0.sh b/.github/hooks/scripts/pretooluse-0.sh index 468b895b..14198e2f 100644 --- a/.github/hooks/scripts/pretooluse-0.sh +++ b/.github/hooks/scripts/pretooluse-0.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# agentsmesh-matcher: Edit|Write -# agentsmesh-command: eslint --fix +# agentsmesh-matcher: Bash +# agentsmesh-command: echo "Running: $(jq -r '.tool_input.command' < /dev/stdin)" set -e HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -eslint --fix +echo "Running: $(jq -r '.tool_input.command' < /dev/stdin)" diff --git a/.junie/AGENTS.md b/.junie/AGENTS.md index c950ff5a..885af26e 100644 --- a/.junie/AGENTS.md +++ b/.junie/AGENTS.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.junie/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.junie/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.junie/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.junie/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.roo/rules/00-root.md b/.roo/rules/00-root.md index 35251408..cd47a9bf 100644 --- a/.roo/rules/00-root.md +++ b/.roo/rules/00-root.md @@ -2,91 +2,72 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.roo/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.roo/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.roo/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.roo/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/.windsurf/hooks.json b/.windsurf/hooks.json index 05a4fac6..419d5486 100644 --- a/.windsurf/hooks.json +++ b/.windsurf/hooks.json @@ -2,13 +2,13 @@ "hooks": { "pre_tool_use": [ { - "command": "eslint --fix", + "command": "echo \"Running: $(jq -r '.tool_input.command' < /dev/stdin)\"", "show_output": true } ], "post_tool_use": [ { - "command": "Review the file content for any security concerns", + "command": "jq -r '.tool_input.file_path' | xargs eslint --fix", "show_output": true } ] diff --git a/AGENTS.md b/AGENTS.md index 067ff783..766a0b67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,88 +2,69 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.agents/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.agents/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.agents/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.agents/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs @@ -94,4 +75,4 @@ ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 672bcf30..6c145a3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.2.10 + +### Patch Changes + +- Align `agentsmesh init` default `targets` with the shared target catalog (`TARGET_IDS`) so new configs include every supported tool without a duplicate list. Shorten the AgentsMesh sourcing note appended to generated root instructions. + ## 0.2.9 ### Patch Changes diff --git a/GEMINI.md b/GEMINI.md index b6001715..901b0e0f 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -2,88 +2,69 @@ ## Session Start -- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work -- Apply relevant lessons to the current task +- Read `tasks/lessons.md` before doing any work. Apply relevant lessons. -## Workflow Orchestration +## Workflow -### 1. Plan Node Default +### Planning -- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) -- If something goes sideways, STOP and re-plan immediately - don't keep pushing -- Use plan mode for verification steps, not just building -- Write detailed specs upfront to reduce ambiguity +- Enter plan mode for any non-trivial task (3+ steps or architectural decisions). Write plan to `tasks/todo.md`. +- If something goes sideways, STOP and re-plan — don't keep pushing. +- Check in before starting implementation. Mark items complete as you go. -### 2. Subagent Strategy +### Subagents -- Use subagents liberally to keep main context window clean -- Offload research, exploration, and parallel analysis to subagents -- For complex problems, throw more compute at it via subagents -- One tack per subagent for focused execution +- Use subagents liberally for research, exploration, and parallel analysis. One tack per subagent. -### 3. Self-Improvement Loop +### Lessons -- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made -- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake -- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes -- Write rules for yourself that prevent the same mistake -- Ruthlessly iterate on these lessons until mistake rate drops -- Review lessons at session start for relevant project +- **When**: user correction, test failure, CI failure, code review feedback, or any other mistake signal. +- **How**: add a bullet to `tasks/lessons.md` with (1) what went wrong, (2) root cause, (3) a rule that prevents recurrence. +- This is the primary cross-session memory — ruthlessly iterate until mistake rate drops. -### 4. Verification Before Done +### Verification -- Never mark a task complete without proving it works -- **After every feature/story completion**: Use the `post-feature-qa` skill (`.gemini/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done -- Diff behavior between main and your changes when relevant +- Never mark a task complete without proving it works — run tests, check logs, demonstrate correctness. +- After every feature/story: use `post-feature-qa` skill (`.gemini/skills/post-feature-qa/`). - Ask yourself: "Would a staff engineer approve this?" -- Run tests, check logs, demonstrate correctness -### 5. Demand Elegance (Balanced) +### Elegance - For non-trivial changes: pause and ask "is there a more elegant way?" -- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" -- Skip this for simple, obvious fixes - don't over-engineer -- Challenge your own work before presenting it +- Skip this for simple, obvious fixes — don't over-engineer. -### 6. Autonomous Bug Fixing +### Bug Fixing -- When given a bug report: just fix it. Don't ask for hand-holding -- Point at logs, errors, failing tests - then resolve them -- Zero context switching required from the user -- Go fix failing CI tests without being told how - -## Task Management - -1. **Plan First**: Write plan to `tasks/todo.md` with checkable items -2. **Verify Plan**: Check in before starting implementation -3. **Track Progress**: Mark items complete as you go -4. **Explain Changes**: High-level summary at each step -5. **Document Results**: Add review section to `tasks/todo.md` -6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above +- When given a bug report: just fix it. Find root cause, point at logs/errors, resolve. Zero hand-holding. ## Skills -- **post-feature-qa** (`.gemini/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. -- **add-agent-target** (`.gemini/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. +- **post-feature-qa** — Apply after every feature/story. Senior QA: verify edge-case coverage and story alignment. +- **add-agent-target** — Use when adding a new AI agent target. Covers research, implementation, fixtures, full test coverage, docs. ## Core Principles -- **Simplicity First**: Make every change as simple as possible. Impact minimal code. +- **Simplicity**: Make every change as simple as possible. Only touch what's necessary. - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. -- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. -## Project-Specific Rules +## Project Rules -- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. +- **TDD mandatory**: Write failing tests FIRST, then implement. - **Max file size**: 200 lines. Split by responsibility if larger. - **No classes unless stateful**: Prefer pure functions + types. - **No `any`**: Use `unknown` + narrowing. - **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. - **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. -- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. +- **Generated artifact tests must be strict**: Assert exact file paths, exact file counts, and exact referenced wrapper/script sets. No loose checks (`some(...)`, prefix-only, "at least one"). - **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` -- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. -- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. +- **Docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in both `README.md` and the website (`website/src/content/docs/`) before the task is marked complete. +- **Target data single source of truth** — do **not** hardcode target lists or support levels outside this chain: + 1. `src/targets/catalog/target-ids.ts` (`TARGET_IDS`) = canonical target ID list. Each target's `capabilities` in `src/targets//index.ts` = feature support levels. + 2. `src/core/matrix/data.ts` (`SUPPORT_MATRIX`) = built dynamically from descriptors. Never hardcode. + 3. `website/src/content/docs/reference/supported-tools.mdx` = **single docs page** for per-target support. All other pages link here — no duplicate tables. + 4. `README.md` matrix must stay in sync with code capabilities. + 5. No hardcoded target counts or enumerations on homepage, CLI overview, or other pages. Use generic language and link to the matrix. + 6. Adding/changing a target: update `target-ids.ts` + descriptor → `supported-tools.mdx` → `README.md` matrix. No other docs pages should need changes. - **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions - **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs @@ -100,4 +81,4 @@ ## AgentsMesh Generation Contract -AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. \ No newline at end of file +AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss. \ No newline at end of file diff --git a/ROADMAP.md b/ROADMAP.md index a15d2530..7bb31860 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,4 +1,4 @@ -# Roadmap +# AgentsMesh Roadmap Based on community feedback, GitHub issue analysis, and AgentsMesh's existing strengths. @@ -6,154 +6,258 @@ Based on community feedback, GitHub issue analysis, and AgentsMesh's existing st - Close gaps that block adoption before adding novel features. - Leverage existing advantages (permissions, lock files, diff, lint, watch, local overrides) that users are actively requesting. -- Prioritize features by community demand signal. +- Prioritize features by community demand signal (reactions, comments, recurring requests). - Reduce daily friction, not just configuration complexity. -## Current Advantages +## Shipped + +| Feature | Status | Notes | +| ------------------------------ | -------- | ---------------------------------------------- | +| Permissions syncing | Shipped | Frequently requested, rarely available | +| Lock file + merge | Shipped | Not available in most tools | +| `diff` command | Shipped | Most tools only offer `--dry-run` on generate | +| `lint` command | Shipped | Not available in most tools | +| `watch` mode | Shipped | Not available in most tools | +| Local overrides (`local.yaml`) | Shipped | Frequently requested | +| Link rebasing | Shipped | Frequently requested | +| `matrix` command | Shipped | Not available in most tools | +| Broad target coverage | Shipped | See [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for the full list | +| Community catalog (website) | Shipped | Skills, agents, commands explorer on homepage | +| Pack install + sync | Shipped | `install`, `install --sync`, `installs.yaml` | -AgentsMesh already ships several features that users of other AI config tools are actively requesting: +--- -| Feature | Status | Common gap elsewhere | -|-----------------------------|---------|-----------------------------------------------| -| Permissions syncing | Shipped | Frequently requested, rarely available | -| Lock file + merge | Shipped | Not available in most tools | -| `diff` command | Shipped | Most tools only offer `--dry-run` on generate | -| `lint` command | Shipped | Not available in most tools | -| `watch` mode | Shipped | Not available in most tools | -| Local overrides | Shipped | Frequently requested | -| Link rebasing | Shipped | Not available elsewhere | -| Compatibility `matrix` | Shipped | Not available in most tools | +## Tier 1: Close the Gaps (Must-Have) ---- +### 1. More Agent Targets + +11 tools is good. Breadth remains one of the biggest adoption drivers. The AI coding tool space is growing fast. + +Priority targets based on community demand: + +- **Kiro** (Amazon's new AI IDE — already drawing attention) +- **Goose** (Block's open-source agent, developer-friendly) +- **OpenCode** (terminal-first, growing community) +- **Kilo Code** (Cline fork, distinct config surface) +- **Factory Droid** (enterprise-focused agent) +- **Amp** (new entrant, getting traction) -## Tier 1: Close the Gaps +### 2. Global Mode -### Global Mode +User-level configs across all projects. One of the most-voted feature requests across the AI config tooling community. Expands AgentsMesh from project-scoped to personal developer workflow. -User-level configs across all projects. Expands AgentsMesh from project-scoped to personal developer workflow. +Goals: - Support personal/global rules outside a single repo (`~/.agentsmesh/`) - Define merge precedence between global and project-local config -- Cover tools that have native global support (Claude Code, Codex CLI, Gemini CLI) +- Cover tools that have native global support (Claude Code, Codex CLI, Gemini CLI, etc.) -### Programmatic API +### 3. Plugin System for Custom Targets -Expose `import { generate, lint, diff } from 'agentsmesh'` for CI scripts, custom tooling, and automated pipelines. +Let users add custom targets without forking. The highest-leverage adoption feature for a sync library — it makes every niche AI tool compatible without core PRs. -- Export core functions as a stable public API -- Enable CI/CD integration without CLI subprocess spawning -- Support IDE plugin development +Goals: -### More Agent Targets +- Define a stable target plugin interface +- `agentsmesh plugin add ./my-custom-target` +- Community-contributed targets ship independently of the core release cycle +- Plugin registry page on the website -AgentsMesh supports 9 tools. Breadth remains one of the biggest adoption drivers. +### 4. Distribution: Homebrew + Single Binary -Priority targets based on community demand: -- Roo Code / Kilo Code (Cline forks with distinct config) -- Goose -- Kiro -- OpenCode -- Factory Droid -- Google Antigravity +Most developers expect `brew install agentsmesh` and a standalone binary. AgentsMesh currently requires Node.js >=20. -### Distribution: Homebrew + Single Binary +Goals: - Publish Homebrew formula - Ship Node.js SEA (Single Executable Application) binary - Remove Node.js as a prerequisite for non-JS developers -### `--json` Flag on All Commands +### 5. JSON Schema for Config Files + +Provide schema files for IDE autocomplete and validation. Extremely high ROI — zero extra tooling needed by users, big reduction in config errors. + +Goals: + +- Publish JSON Schema for `agentsmesh.yaml` +- Enable IntelliSense in VSCode, JetBrains, etc. +- Publish to SchemaStore so it works with zero user config + +### 6. `--json` Flag on All Commands Machine-readable output for scripting and CI pipelines. +Goals: + - Add `--json` to `generate`, `diff`, `lint`, `check`, `matrix` - Structured output for programmatic consumption -### `.gitignore` Command +--- + +## Tier 2: Differentiate (High Impact) + +### 7. Community Registry — Full Publishing + +The catalog MVP is live on the website. The next step is a full publish-and-discovery workflow so developers can share their own packs. + +Goals: + +- Submit a pack to the registry via PR or CLI (`agentsmesh publish`) +- Version pinning with changelog visibility in catalog +- Ratings, downloads, or star counts for social proof +- `agentsmesh install @registry/pack-name` shorthand + +### 8. Programmatic API + +Expose `import { generate, lint, diff } from 'agentsmesh'` for CI scripts, custom tooling, and automated pipelines. + +Goals: + +- Export core functions as a stable public API +- Enable CI/CD integration without CLI subprocess spawning +- Support IDE plugin development + +### 9. MCP Server (Self-Serve) + +Expose AgentsMesh as an MCP tool so AI agents can self-configure. Increasingly requested by teams building agentic workflows. + +Goals: + +- Implement MCP server with CRUD operations for rules, commands, agents +- Let agents introspect their own configuration +- Enable "AI configures AI" workflows + +### 10. `.gitattributes` Auto-Generation + +Mark generated files as `linguist-generated` to reduce PR noise and GitHub language statistics pollution. + +Goals: + +- Auto-generate `.gitattributes` entries for all generated config files +- Clean PR diffs — generated files collapse by default on GitHub + +### 11. `.gitignore` Command Auto-maintain `.gitignore` entries for generated AI config files. +Goals: + - `agentsmesh gitignore` to add/update entries - Respect `--targets` and `--features` filters -- Idempotent -- safe to run repeatedly +- Idempotent — safe to run repeatedly -### MCP Server +### 12. `convert` Command -Expose AgentsMesh as an MCP tool so AI agents can inspect and manage their own configuration. +Direct tool-to-tool conversion without going through canonical format. One of the oldest migration requests in the community. -- CRUD operations for rules, commands, agents -- Agent self-introspection -- "AI configures AI" workflows +Goals: ---- +- `agentsmesh convert --from cursor --to claude-code` +- Useful for quick migrations without full canonical setup -## Tier 2: Differentiate +--- -### `.gitattributes` Auto-Generation +## Tier 3: Win the Ecosystem -Mark generated files as `linguist-generated` to reduce PR noise and GitHub language statistics pollution. +### 13. IDE Extension -### `convert` Command +VSCode / JetBrains plugin for visual config editing. High effort but the most visible differentiator for team adoption. -Direct tool-to-tool conversion without going through canonical format. +Goals: -```bash -agentsmesh convert --from cursor --to claude-code -``` +- Visual compatibility matrix +- Config editing with autocomplete and JSON Schema +- One-click generate/diff/lint +- Status bar showing drift state -### Ephemeral Mode +### 14. Ephemeral Mode Generate configs temporarily without writing to the filesystem. +Goals: + - `agentsmesh generate --stdout` for piping - `agentsmesh generate --temp` for Docker builds, CI, testing +- No persistent file writes -### Plugin System for Custom Targets +### 15. `migrate` Command -Let users add custom targets without forking. - -- Define a target plugin interface -- `agentsmesh plugin add ./my-custom-target` -- Community-contributed targets without core PRs +`agentsmesh migrate --from ` — import existing AI config directories directly into `.agentsmesh/`. Different from `import`: opinionated, zero-friction, single-command. -### JSON Schema for Config Files +Goals: -Provide schema files for IDE autocomplete and validation in VS Code, JetBrains, and other editors. +- Zero-friction migration from other tools +- Map existing config formats to `agentsmesh.yaml` +- Preserve all rules, commands, subagents, skills, MCP, hooks, ignore --- -## Tier 3: Win the Ecosystem +## Known Failure Patterns to Prevent -### Community Registry +These are common failure modes in AI config tooling, extracted from community bug reports and user feedback. AgentsMesh's design explicitly guards against them. -`agentsmesh install @org/shared-rules` -- a package registry for rule sets, skills, and configs with discovery, versioning, and pinning. +| Pattern | Prevention Strategy | +| ------------------------------- | -------------------------------------------------------------------------------------- | +| Import breaks on edge cases | Exhaustive import testing: empty frontmatter, subdirectories, alternate file locations | +| Path separator issues (Windows) | Normalize all paths to POSIX; test on Windows CI | +| Duplicate/conflicting outputs | Validate output paths for cross-target collisions before writing | +| Global vs local scope confusion | Clear error messages + lint warnings when scope is ambiguous | +| Frontmatter validation | Lint catches missing/malformed frontmatter before generate | +| Hook script path references | Copy referenced hook scripts to target directories | -### `migrate` Command +--- -`agentsmesh migrate --from ` -- zero-friction import from other AI config management tools directly into `.agentsmesh/`. +## Suggested Release Order -### IDE Extension +### v0.3 -VS Code / JetBrains plugin for visual config editing, compatibility matrix, and one-click generate/diff/lint. +- Global mode (`~/.agentsmesh/`) +- Homebrew + single binary distribution +- JSON Schema for config files (SchemaStore) +- 2–3 new targets (Kiro, Goose, OpenCode) ---- +### v0.4 -## Suggested Release Order +- Plugin system for custom targets +- `--json` flag on all commands +- Community registry — full publish workflow + +### v0.5 + +- Programmatic API +- MCP server (self-serve) +- `convert` command +- `.gitattributes` auto-generation +- `.gitignore` command + +### v0.6 -| Version | Focus | -|---------|------------------------------------------------------------------------| -| v0.3 | 3-5 new targets, `.gitignore` command, `.gitattributes`, `--json` flag | -| v0.4 | Global mode, Homebrew + single binary, JSON Schema | -| v0.5 | Programmatic API, MCP server, `convert` command | -| v0.6 | Plugin system, ephemeral generation, community registry MVP | -| v0.7 | `migrate` command, IDE extension, registry discovery | +- `migrate` command +- IDE extension (VSCode) +- Ephemeral generation mode +- Registry discovery and versioning --- ## Priority by Goal -**Adoption:** More targets > Distribution > Global mode > `migrate` +### If the goal is adoption + +1. More targets (especially Kiro, Goose) +2. Distribution (Homebrew/binary) +3. Plugin system (removes the ceiling on target coverage) +4. Global mode + +### If the goal is differentiation + +1. Plugin system (nobody in this space has this) +2. `.gitattributes` auto-generation (nobody has this) +3. MCP server for self-configuration +4. Full community registry with publishing -**Differentiation:** `.gitattributes` > Plugin system > MCP server > Ephemeral mode +### If the goal is team/enterprise value -**Team/Enterprise:** Programmatic API > `--json` output > JSON Schema > Community registry +1. Programmatic API +2. `--json` output +3. JSON Schema for IDE support +4. `migrate` command (zero-friction onboarding) diff --git a/package.json b/package.json index 3fa940f5..0909cc9e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agentsmesh", - "version": "0.2.9", + "version": "0.2.10", "description": "One canonical source for AI coding agent rules, commands, skills, MCP, hooks, and permissions — synced across Claude Code, Cursor, Copilot, Continue, Junie, Gemini CLI, Cline, Codex CLI, Windsurf, Antigravity, and Roo Code.", "type": "module", "main": "./dist/cli.js", diff --git a/src/cli/commands/init-templates.ts b/src/cli/commands/init-templates.ts index 3576e819..8b4b18a7 100644 --- a/src/cli/commands/init-templates.ts +++ b/src/cli/commands/init-templates.ts @@ -2,17 +2,7 @@ * Template data for agentsmesh init command. */ -const ALL_TARGETS = [ - 'claude-code', - 'cursor', - 'copilot', - 'continue', - 'junie', - 'gemini-cli', - 'cline', - 'codex-cli', - 'windsurf', -]; +import { TARGET_IDS } from '../../targets/catalog/target-ids.js'; const ALL_FEATURES = [ 'rules', @@ -30,7 +20,7 @@ const ALL_FEATURES = [ * @param targets - Target tool IDs to include; uses all targets if empty */ export function buildConfig(targets: string[]): string { - const targetList = (targets.length > 0 ? targets : ALL_TARGETS).map((t) => ` - ${t}`).join('\n'); + const targetList = (targets.length > 0 ? targets : TARGET_IDS).map((t) => ` - ${t}`).join('\n'); const featureList = ALL_FEATURES.map((f) => ` - ${f}`).join('\n'); return `version: 1\ntargets:\n${targetList}\nfeatures:\n${featureList}\n`; } diff --git a/src/targets/projection/root-instruction-paragraph.ts b/src/targets/projection/root-instruction-paragraph.ts index 7d645047..a42e209f 100644 --- a/src/targets/projection/root-instruction-paragraph.ts +++ b/src/targets/projection/root-instruction-paragraph.ts @@ -1,21 +1,30 @@ -/** Body text shipped before the `.agentsmesh/` substring was removed from generated targets (import/strip compatibility). */ -const ROOT_INSTRUCTION_BODY_LEGACY = +/** Body v1: original text with `.agentsmesh/` substring. */ +const ROOT_INSTRUCTION_BODY_V1 = "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is `.agentsmesh/`; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; -/** Avoid the `.agentsmesh/` substring so generated targets stay free of canonical path tokens in prose (link-rewrite e2e contract). */ -const ROOT_INSTRUCTION_BODY = +/** Body v2: removed `.agentsmesh/` substring to satisfy the link-rewrite e2e contract. */ +const ROOT_INSTRUCTION_BODY_V2 = "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; -const LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = ROOT_INSTRUCTION_BODY_LEGACY; +/** Body v3 (current): optimized for brevity. Avoids `.agentsmesh/` substring. */ +const ROOT_INSTRUCTION_BODY = + 'AgentsMesh syncs AI coding tool configuration from a single canonical `.agentsmesh` directory. All target-specific files (`.claude/`, `.cursor/`, `AGENTS.md`, etc.) are generated artifacts — edit canonical config first, then regenerate. The import/generate contract is bidirectional and lossless: embedded or projected features round-trip without data loss.'; + +const LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = ROOT_INSTRUCTION_BODY_V1; const LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION = `## Project-Specific Rules -${ROOT_INSTRUCTION_BODY_LEGACY}`; +${ROOT_INSTRUCTION_BODY_V1}`; + +/** Prior shipped heading + v1 body (still stripped on import after wording change). */ +const AGENTSMESH_CONTRACT_WITH_V1_BODY = `## AgentsMesh Generation Contract + +${ROOT_INSTRUCTION_BODY_V1}`; -/** Prior shipped heading + legacy body (still stripped on import after wording change). */ -const AGENTSMESH_CONTRACT_WITH_LEGACY_BODY = `## AgentsMesh Generation Contract +/** Prior shipped heading + v2 body (still stripped on import after wording change). */ +const AGENTSMESH_CONTRACT_WITH_V2_BODY = `## AgentsMesh Generation Contract -${ROOT_INSTRUCTION_BODY_LEGACY}`; +${ROOT_INSTRUCTION_BODY_V2}`; export const AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = `## AgentsMesh Generation Contract @@ -25,42 +34,24 @@ function normalizeWhitespace(value: string): string { return value.replace(/\s+/g, ' ').trim(); } +/** All legacy paragraph forms, newest first. Each is tried for upgrade/strip. */ +const LEGACY_FORMS = [ + AGENTSMESH_CONTRACT_WITH_V2_BODY, + AGENTSMESH_CONTRACT_WITH_V1_BODY, + LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, + LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, +]; + export function appendAgentsmeshRootInstructionParagraph(content: string): string { const trimmed = content.trim(); - if ( - normalizeWhitespace(trimmed).includes( - normalizeWhitespace(AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH), - ) - ) { + const norm = normalizeWhitespace(trimmed); + if (norm.includes(normalizeWhitespace(AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH))) { return trimmed; } - if ( - normalizeWhitespace(trimmed).includes( - normalizeWhitespace(LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION), - ) - ) { - return trimmed.replace( - LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, - AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, - ); - } - if ( - normalizeWhitespace(trimmed).includes(normalizeWhitespace(AGENTSMESH_CONTRACT_WITH_LEGACY_BODY)) - ) { - return trimmed.replace( - AGENTSMESH_CONTRACT_WITH_LEGACY_BODY, - AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, - ); - } - if ( - normalizeWhitespace(trimmed).includes( - normalizeWhitespace(LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH), - ) - ) { - return trimmed.replace( - LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, - AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, - ); + for (const legacy of LEGACY_FORMS) { + if (norm.includes(normalizeWhitespace(legacy))) { + return trimmed.replace(legacy, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH); + } } return trimmed ? `${trimmed}\n\n${AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}` @@ -68,10 +59,10 @@ export function appendAgentsmeshRootInstructionParagraph(content: string): strin } export function stripAgentsmeshRootInstructionParagraph(content: string): string { - return content - .replace(`\n\n${AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}`, '') - .replace(`\n\n${AGENTSMESH_CONTRACT_WITH_LEGACY_BODY}`, '') - .replace(`\n\n${LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION}`, '') - .replace(`\n\n${LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}`, '') - .trim(); + let result = content; + result = result.replace(`\n\n${AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}`, ''); + for (const legacy of LEGACY_FORMS) { + result = result.replace(`\n\n${legacy}`, ''); + } + return result.trim(); } diff --git a/tests/e2e/agents-last-run.md b/tests/e2e/agents-last-run.md index d6b02ffa..1f286653 100644 --- a/tests/e2e/agents-last-run.md +++ b/tests/e2e/agents-last-run.md @@ -1,6 +1,6 @@ # Agents E2E Last Run Report -_Generated: 2026-03-29T14:43:53.355Z_ +_Generated: 2026-03-31T09:35:22.043Z_ ## Initial — `.agentsmesh/agents/` (canonical fixture) diff --git a/tests/unit/targets/root-instruction-paragraph.test.ts b/tests/unit/targets/root-instruction-paragraph.test.ts index 2f4580de..b309bd31 100644 --- a/tests/unit/targets/root-instruction-paragraph.test.ts +++ b/tests/unit/targets/root-instruction-paragraph.test.ts @@ -5,11 +5,17 @@ import { } from '../../../src/targets/projection/root-instruction-paragraph.js'; describe('appendAgentsmeshRootInstructionParagraph', () => { + const LEGACY_BODY_V1 = + "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is `.agentsmesh/`; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; + + const LEGACY_BODY_V2 = + "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; + it('appends the headed section to plain content', () => { const result = appendAgentsmeshRootInstructionParagraph('First'); expect(result).toContain('First'); expect(result).toContain('## AgentsMesh Generation Contract'); - expect(result).toContain('AgentsMesh is a config sync library for AI coding tools.'); + expect(result).toContain('AgentsMesh syncs AI coding tool configuration'); expect(result).not.toContain('.agentsmesh/'); }); @@ -17,42 +23,41 @@ describe('appendAgentsmeshRootInstructionParagraph', () => { const result = appendAgentsmeshRootInstructionParagraph( `First\n\n${AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}`, ); - expect(result.match(/AgentsMesh is a config sync library for AI coding tools\./g)).toHaveLength( - 1, - ); + expect(result.match(/AgentsMesh syncs AI coding tool configuration/g)).toHaveLength(1); expect(result.match(/## AgentsMesh Generation Contract/g)).toHaveLength(1); }); - it('upgrades the legacy paragraph without a heading', () => { - const legacyParagraph = - "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is `.agentsmesh/`; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; - const result = appendAgentsmeshRootInstructionParagraph(`First\n\n${legacyParagraph}`); + it('upgrades the v1 legacy paragraph without a heading', () => { + const result = appendAgentsmeshRootInstructionParagraph(`First\n\n${LEGACY_BODY_V1}`); expect(result).toContain('## AgentsMesh Generation Contract'); - expect(result.match(/AgentsMesh is a config sync library for AI coding tools\./g)).toHaveLength( - 1, - ); + expect(result).toContain('AgentsMesh syncs AI coding tool configuration'); expect(result).not.toContain('.agentsmesh/'); }); - it('replaces the old example heading with the current one', () => { - const oldSection = - "## Project-Specific Rules\n\nAgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is `.agentsmesh/`; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; + it('replaces the old Project-Specific Rules heading with the current one', () => { + const oldSection = `## Project-Specific Rules\n\n${LEGACY_BODY_V1}`; const result = appendAgentsmeshRootInstructionParagraph(`First\n\n${oldSection}`); expect(result).toContain('## AgentsMesh Generation Contract'); expect(result).not.toContain('## Project-Specific Rules'); - expect(result.match(/AgentsMesh is a config sync library for AI coding tools\./g)).toHaveLength( - 1, - ); + expect(result).toContain('AgentsMesh syncs AI coding tool configuration'); expect(result).not.toContain('.agentsmesh/'); }); - it('upgrades the prior AgentsMesh contract heading that used the legacy body', () => { - const legacyParagraph = - "AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is `.agentsmesh/`; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports."; - const oldContract = `First\n\n## AgentsMesh Generation Contract\n\n${legacyParagraph}`; + it('upgrades the v1 body under the current heading', () => { + const oldContract = `First\n\n## AgentsMesh Generation Contract\n\n${LEGACY_BODY_V1}`; const result = appendAgentsmeshRootInstructionParagraph(oldContract); expect(result).toContain('## AgentsMesh Generation Contract'); expect(result.match(/## AgentsMesh Generation Contract/g)).toHaveLength(1); expect(result).not.toContain('.agentsmesh/'); + expect(result).toContain('AgentsMesh syncs AI coding tool configuration'); + }); + + it('upgrades the v2 body under the current heading', () => { + const v2Contract = `First\n\n## AgentsMesh Generation Contract\n\n${LEGACY_BODY_V2}`; + const result = appendAgentsmeshRootInstructionParagraph(v2Contract); + expect(result).toContain('## AgentsMesh Generation Contract'); + expect(result.match(/## AgentsMesh Generation Contract/g)).toHaveLength(1); + expect(result).toContain('AgentsMesh syncs AI coding tool configuration'); + expect(result).not.toContain('The only canonical source of truth'); }); }); diff --git a/website/src/content/docs/canonical-config/agents.mdx b/website/src/content/docs/canonical-config/agents.mdx index 2453a7de..b4258e1f 100644 --- a/website/src/content/docs/canonical-config/agents.mdx +++ b/website/src/content/docs/canonical-config/agents.mdx @@ -60,17 +60,7 @@ Suggest concrete fixes, not vague recommendations. ## Tool-specific behavior -| Tool | Support | Notes | -|------|---------|-------| -| Claude Code | Native | Maps directly to Claude Code agent format. | -| Cursor | Native | Maps to Cursor agent definition format. | -| Copilot | Native | Maps to Copilot agent definition. | -| Gemini CLI | Native | Maps to Gemini CLI agent format. | -| Cline | Embedded | Projected as a skill with metadata for round-trip. | -| Codex CLI | Native | Maps to Codex CLI agent format. | -| Windsurf | Embedded | Projected as a skill with metadata. | -| Continue | — | Not supported. | -| Junie | Embedded | Projected as a skill with metadata. | +See the **Agents** row in the [supported tools matrix](/agentsmesh/reference/supported-tools/) for per-target support levels (native, embedded, or unsupported).