@dezkareid/ai-team 1.4.6 → 1.4.7

package/.agent-structurerc

@@ -38,7 +38,7 @@
   "mcpServers": {
     "ai-team": {
       "claude-plugin": "company-context",
-      "version": "1.4.6",
+      "version": "1.4.7",
       "package": "@dezkareid/ai-team",
       "command": "npx",
       "args": [

package/AGENTS.md

@@ -38,49 +38,191 @@ Command content with {SCRIPT} and {{args}} placeholders.
 
 ### Organization
 
+- **`commands/`**: Source command files in TOML format, primarily used by Gemini CLI.
+- **`skills/`**: Source skill files (SKILL.md), providing specialized knowledge and instructions.
+- **`plugins/`**: Claude Code plugins. Each subdirectory represents a plugin and contains exported versions of commands and skills in Markdown format.
+- **`.claude-plugin/`**: Metadata and configuration for Claude Code. The root folder contains the `marketplace.json`, while plugin folders contain their respective `plugin.json`.
 
-### Argument Patterns
-
-Different agents use different argument placeholders:
-
-- **Markdown/prompt-based**: `$ARGUMENTS`
-- **TOML-based**: `{{args}}`
-
-## Development
-
-Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.
+#### Project Configuration (`.agent-structurerc`)
 
 File `.agent-structurerc` is used to configure the project structure.
 
 ```json
 {
-    "claude-plugins": {
-        "npm-tools": {
-            "name": "npm-tools",
-            "description": "Tools for working with npm"
-        }
+  "claude-plugins": {
+    "npm-tools": {
+      "name": "npm-tools",
+      "version": "0.0.1",
+      "description": "Tools for working with npm"
+    },
+    "design-system": {
+      "name": "design-system",
+      "version": "0.0.1",
+      "description": "Authoritative design system context and tools"
     },
-    "commands": [
-        {
-            "id": "npm-package-setup",
-            "source": "npm/package-setup.toml",
-            "claude-plugin": "npm-tools"
-        }
-    ]
+    "company-context": {
+      "name": "company-context",
+      "version": "0.0.3",
+      "description": "Authoritative company context and tools"
+    }
+  },
+  "commands": [
+    {
+      "name": "npm-package-setup",
+      "source": "npm/package-setup.toml",
+      "claude-plugin": "npm-tools"
+    },
+    {
+      "name": "npm-publish",
+      "source": "npm/publish-setup.toml",
+      "claude-plugin": "npm-tools"
+    }
+  ],
+  "skills": [
+    {
+      "name": "design-tokens",
+      "source": "skills/design-tokens/SKILL.md",
+      "claude-plugin": "design-system"
+    }
+  ],
+  "mcpServers": {
+    "ai-team": {
+      "claude-plugin": "company-context",
+      "version": "1.4.6",
+      "package": "@dezkareid/ai-team",
+      "command": "npx",
+      "args": [
+        "-y",
+        "${package}@${version}"
+      ],
+      "contextFiles": {
+        "get_company_outcomes": "context/outcomes.md",
+        "get_architecture_principles": "context/architecture-principles.md"
+      }
+    }
+  }
 }
 ```
 
-### Claude Plugin Structure
+#### Claude Plugin Structure
 
 ```
 plugins/
 └── <claude-plugin>/
     ├── .claude-plugin/
     │   ├── plugin.json
-    ├──commands/
+    ├── commands/ (optional)
     │   ├── <command-name>.md
+    ├── skills/ (optional)
+    │   └── <skill-name>/
+    │       └── SKILL.md
+    └── .mcp.json (optional)
+```
+
+### Argument Patterns
+
+Different agents use different argument placeholders:
+
+- **Markdown/prompt-based**: `$ARGUMENTS`
+- **TOML-based**: `{{args}}`
+
+## Development
+
+Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.
+
+### Workflow
+
+The project uses a structured workflow to keep versions, commands, and configurations in sync across Gemini and Claude platforms.
+
+```mermaid
+graph TD
+    subgraph "Phase 1: Sync Version"
+        P[package.json] -- sync-version --> AS[.agent-structurerc]
+        P -- sync-version --> M[.claude-plugin/marketplace.json]
+        P -- sync-version --> GE[gemini-extension.json]
+    end
+
+    subgraph "Phase 2: Export to Claude"
+        CMD[commands/*.toml] -- export-claude --> P_CMD[plugins/commands/*.md]
+        SKL[skills/**] -- export-claude --> P_SKL[plugins/skills/**]
+        AS -- export-claude --> P_JSON[plugins/**/plugin.json]
+        P_JSON -- updates --> M
+    end
+
+    subgraph "Phase 3: Distribute MCP"
+        AS -- distribute-mcp --> GE
+        AS -- distribute-mcp --> PM[plugins/company-context/.mcp.json]
+    end
+```
+
+> **Note**: You must run `pnpm run build` before executing these commands, as they rely on the compiled files in the `dist/` directory.
+
+1.  **Sync Version**: Run `pnpm run sync-version` to propagate the version from `package.json` to `.agent-structurerc` (specifically `mcpServers`), `.claude-plugin/marketplace.json`, and `gemini-extension.json`.
+2.  **Export to Claude**: Run `pnpm run export-claude` to process source files.
+    -   **Commands**: Converts TOML source files to Markdown with Claude-compatible frontmatter and `$ARGUMENTS` placeholders.
+    -   **Skills**: Symlinks `SKILL.md` and reference files into the `plugins/` directory.
+    -   **Plugin Versions**: Updates `plugin.json` in each plugin folder and reflects them in the `marketplace.json`.
+3.  **Distribute MCP**: Run `pnpm run distribute-mcp` to resolve placeholders (like `${version}`) in MCP configurations defined in `.agent-structurerc`.
+    -   Updates `gemini-extension.json` for Gemini CLI.
+    -   Creates/updates `.mcp.json` in relevant plugin folders (e.g., `plugins/company-context/`) for Claude Code.
+
+### Versioning Skills and Plugins
+
+Skills and plugins are versioned independently using changeset files (powered by `@changesets/cli`).
+
+#### Version sources
+
+| Artifact | Where the version lives |
+|---|---|
+| **Skill** | `metadata.version` field in the skill's `SKILL.md` frontmatter |
+| **Plugin** | `version` field under `claude-plugins.<id>` in `.agent-structurerc` |
+
+#### Changeset file format
+
+Create a file inside `.changeset/` (any name, `.md` extension). The frontmatter lists one or more names and their bump type (`major`, `minor`, or `patch`). The same name can appear in both scripts — each one only acts on its own registry.
+
+```md
+---
+"design-tokens": minor
+"npm-tools": patch
+---
+
+Brief description of what changed.
+```
+
+Use `pnpm changeset` to generate the file interactively, or create it manually.
+
+#### Applying changesets
+
+```bash
+pnpm run build
+
+# Bump versions in SKILL.md files for any skill listed in pending changesets
+pnpm run apply-skill-changesets
+
+# Bump versions in .agent-structurerc for any plugin listed in pending changesets
+pnpm run apply-plugin-changesets
+```
+
+Each script reads all `.md` files in `.changeset/` (skipping `README.md`), applies the highest bump when a name appears in multiple files, writes the new version to its respective location, and deletes the consumed changeset files.
+
+#### Workflow diagram
+
+```mermaid
+graph TD
+    subgraph "Skill versioning"
+        CS1[.changeset/*.md] -- apply-skill-changesets --> SM[skills/**/SKILL.md\nmetadata.version]
+    end
+
+    subgraph "Plugin versioning"
+        CS2[.changeset/*.md] -- apply-plugin-changesets --> AS[.agent-structurerc\nclaude-plugins.version]
+        AS -- export-claude --> PJ[plugins/**/plugin.json]
+        PJ -- updates --> M[.claude-plugin/marketplace.json]
+    end
 ```
 
+After bumping plugin versions, run `pnpm run export-claude` so the new versions are propagated to `plugin.json` and `marketplace.json`.
+
 ### Commit Rules
 
 Always use Conventional Commits format for commit messages.
@@ -117,3 +259,19 @@ Always prefer use exact versions for dependencies. Do not use `^` or `~`.
 ### Approach
 
 Tests are written using **Vitest** and follow **BDD (Behaviour-Driven Development)** conventions:
+
+- Test files live next to the source files they cover, using the `.spec.ts` suffix.
+- Tests are structured with `describe` blocks that express the context ("given …") and `it` blocks that express the expected behaviour ("should …").
+- Side effects (filesystem, child processes, `process.exit`) are isolated with `vi.mock` / `vi.spyOn` so tests remain fast and deterministic.
+- Pure functions (template generators) are tested without mocks.
+
+### Running Tests
+
+```bash
+# Run the full test suite once
+pnpm test
+```
+
+## Documentation
+
+When a command in templates or npx commands are added/updated/removed/renamed/deprecated, ask to update the AGENTS.md and README.md files.

package/README.md

@@ -31,8 +31,16 @@ claude marketplace add dezkareid-ai-team https://github.com/dezkareid/ai-team
 
 #### `design-system` — Authoritative design system context and tools
 
+| Skill | Description |
+|---|---|
+| `design-tokens` | Authoritative context for the project's design tokens. Provides information on colors, spacing, and breakpoints using CSS custom properties. |
+
 #### `company-context` — Authoritative company context and tools
 
+| MCP Server | Description |
+|---|---|
+| `ai-team` | Provides authoritative company context, outcomes, and architecture principles. |
+
 ### Install a plugin
 
 Once the marketplace is added, install a plugin with:
@@ -42,3 +50,81 @@ claude plugin install npm-tools
 claude plugin install design-system
 claude plugin install company-context
 ```
+
+## Development
+
+### Workflow
+
+The project uses a structured workflow to keep versions, commands, and configurations in sync across Gemini and Claude platforms.
+
+```mermaid
+graph TD
+    subgraph "Phase 1: Sync Version"
+        P[package.json] -- sync-version --> AS[.agent-structurerc]
+        P -- sync-version --> M[.claude-plugin/marketplace.json]
+        P -- sync-version --> GE[gemini-extension.json]
+    end
+
+    subgraph "Phase 2: Export to Claude"
+        CMD[commands/*.toml] -- export-claude --> P_CMD[plugins/commands/*.md]
+        SKL[skills/**] -- export-claude --> P_SKL[plugins/skills/**]
+        AS -- export-claude --> P_JSON[plugins/**/plugin.json]
+        P_JSON -- updates --> M
+    end
+
+    subgraph "Phase 3: Distribute MCP"
+        AS -- distribute-mcp --> GE
+        AS -- distribute-mcp --> PM[plugins/company-context/.mcp.json]
+    end
+```
+
+> **Note**: You must run `pnpm run build` before executing these commands, as they rely on the compiled files in the `dist/` directory.
+
+1.  **Sync Version**: Run `pnpm run sync-version` to propagate the version from `package.json` to `.agent-structurerc`, `.claude-plugin/marketplace.json`, and `gemini-extension.json`.
+2.  **Export to Claude**: Run `pnpm run export-claude` to process source files and update plugins.
+3.  **Distribute MCP**: Run `pnpm run distribute-mcp` to resolve placeholders and update platform-specific MCP configurations.
+
+### Versioning skills and plugins
+
+Skills and plugins follow independent semantic versioning driven by changeset files.
+
+| Artifact | Version location |
+|---|---|
+| **Skill** | `metadata.version` in the skill's `SKILL.md` frontmatter |
+| **Plugin** | `version` under `claude-plugins.<id>` in `.agent-structurerc` |
+
+Create a changeset file in `.changeset/` (use `pnpm changeset` or write it manually):
+
+```md
+---
+"design-tokens": minor
+"npm-tools": patch
+---
+
+Brief description of what changed.
+```
+
+Then apply the changesets:
+
+```bash
+pnpm run build
+pnpm run apply-skill-changesets   # bumps version in SKILL.md
+pnpm run apply-plugin-changesets  # bumps version in .agent-structurerc
+```
+
+After bumping plugin versions, run `pnpm run export-claude` to propagate the new versions to `plugin.json` and `marketplace.json`.
+
+### Organization
+
+- **`commands/`**: Source command files in TOML format (Gemini CLI).
+- **`skills/`**: Source skill files (SKILL.md) for specialized AI knowledge.
+- **`plugins/`**: Exported Claude Code plugins.
+- **`.claude-plugin/`**: Claude marketplace and plugin metadata.
+
+### Testing
+
+Tests are written using **Vitest**:
+
+```bash
+pnpm test
+```

package/gemini-extension.json

@@ -1,12 +1,12 @@
 {
   "name": "dezkareid-ai-team",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "mcpServers": {
     "ai-team": {
       "command": "npx",
       "args": [
         "-y",
-        "@dezkareid/ai-team@1.4.6"
+        "@dezkareid/ai-team@1.4.7"
       ]
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/ai-team",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Repository for AI Team",
   "type": "module",
   "main": "index.js",
@@ -30,12 +30,14 @@
   },
   "homepage": "https://github.com/dezkareid/ai-team#readme",
   "devDependencies": {
+    "@changesets/cli": "2.29.8",
     "@rollup/plugin-commonjs": "29.0.0",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-typescript": "12.3.0",
     "@types/fs-extra": "11.0.4",
     "@types/node": "25.0.10",
+    "@types/semver": "7.7.1",
     "ajv-cli": "5.0.0",
     "rollup": "4.56.0",
     "tslib": "2.8.1",
@@ -47,6 +49,7 @@
     "@iarna/toml": "2.2.5",
     "@modelcontextprotocol/sdk": "1.27.1",
     "fs-extra": "11.3.3",
+    "semver": "7.7.4",
     "yaml": "2.8.2",
     "zod": "4.3.6"
   },
@@ -56,6 +59,8 @@
     "build": "rollup -c",
     "test": "vitest run && npm run test:marketplace",
     "test:marketplace": "ajv validate -s schemas/marketplace.schema.json -d .claude-plugin/marketplace.json",
-    "export-claude": "node dist/cli/export-claude.js"
+    "export-claude": "node dist/cli/export-claude.js",
+    "apply-skill-changesets": "node dist/scripts/apply-skill-changesets.js",
+    "apply-plugin-changesets": "node dist/scripts/apply-plugin-changesets.js"
   }
 }