Local Development

Clone and Install Locally

git clone https://github.com/mubaidr/gem-team.git
cd gem-team

# Dry-run first to preview
apm install . --target claude,cursor --dry-run

# Real install from local path
apm install /absolute/path/to/gem-team --target claude,cursor

Validate the Package

# Marketplace resolution, generated metadata drift, version alignment, audit
apm run check

# Generate a distributable ZIP under build/
apm run pack

apm run check fails if .claude-plugin/marketplace.json is stale. After changing apm.yml or package metadata, regenerate it with apm pack, inspect the diff, and commit the generated file.

Publishable sources are .apm/agents/ and .apm/skills/. build/ contains generated release bundles; direct installs do not require it.

Release Flow

1. Merge changes to main with a conventional commit or PR title.
2. Release Please opens or updates the release PR and bumps apm.yml and version.txt.
3. Regenerate .claude-plugin/marketplace.json when package metadata changes; apm run check enforces reproducibility.
4. Merging the release PR creates the gem-team-v<version> tag and GitHub Release.
5. The release workflow validates the tag and attaches the ZIP and SHA-256 sidecar to the release.

If asset publishing fails after Release Please has created the release, rerun the Publish Release Assets workflow manually with the existing release tag.

Agent and Skill Sources

• Agent definitions: .apm/agents/*.agent.md
• Packaged skills: .apm/skills/*/SKILL.md

The standalone gem-critic agent was removed. gem-reviewer uses review_mode, review_target, and review_scope. Plan validation targets plan; risk-triggered integration validation targets integration. Critic mode is read-only and requires handoff.critic_subject and handoff.critic_context. See .apm/agents/gem-reviewer.agent.md.

When adding or changing a skill, keep its name aligned with the directory name and its description specific enough to support task matching. Rebuild or repack the package before validating generated tool targets.

Docs Site

The docs site lives at docs/src/: a Nuxt 4 app with Nuxt UI & Nuxt Content.

cd docs/src
npm install
npm run dev

See Nuxt Content docs for MDC syntax and authoring.