ai-team 1.0.2 → 1.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  id-token: write # Required for OIDC
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Release
+        run: pnpm release

package/.releaserc.json

@@ -0,0 +1,34 @@
+{
+  "branches": [
+    "main"
+  ],
+  "tagFormat": "v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": true
+      }
+    ],
+    "@semantic-release/github",
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "pnpm-lock.yaml",
+          "CHANGELOG.md"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# [1.1.0](https://github.com/seanwuapps/ai-team/compare/v1.0.2...v1.1.0) (2026-02-23)
+
+
+### Bug Fixes
+
+* implement semantic versioning and release automation ([fe46bdd](https://github.com/seanwuapps/ai-team/commit/fe46bdd03c754fa4cda235001feabda7b7203d4e))
+
+
+### Features
+
+* add version command to CLI and update documentation ([058da9c](https://github.com/seanwuapps/ai-team/commit/058da9c900ac790cea73cfec72902ec0f27a11a1))
+
+# 1.0.0 (2026-02-23)
+
+
+### Bug Fixes
+
+* correct path in bin configuration for ai-team CLI ([016c553](https://github.com/seanwuapps/ai-team/commit/016c55376cb1976117233eca5fbaa7c840e58346))
+* implement semantic versioning and release automation ([fe46bdd](https://github.com/seanwuapps/ai-team/commit/fe46bdd03c754fa4cda235001feabda7b7203d4e))
+
+
+### Features
+
+* add documentation writer agent and enhance code-reviewer tools ([215ebe7](https://github.com/seanwuapps/ai-team/commit/215ebe7a2d87eb85e76c0b30805ee2efd33c80a8))
+* add emoji to agent definitions, enhance descriptions, and update related documentation ([0c169ef](https://github.com/seanwuapps/ai-team/commit/0c169ef194edeb7ca43b49f5da31a257e62988d6))
+* add new agent definitions and update existing ones, enhance README and documentation ([6d9c3ed](https://github.com/seanwuapps/ai-team/commit/6d9c3eda7fb2dab0b3a2df277e644bc3a4cff61e))
+* add new agent definitions for frontend, backend, planning, requirement analysis, testing, and orchestration ([513a162](https://github.com/seanwuapps/ai-team/commit/513a162a94b08729ed3d7bca9e9af8b2babf6ff9))
+* Add styling standards and self-improvement templates ([1d094a9](https://github.com/seanwuapps/ai-team/commit/1d094a93b7c2a116f6bc868a35e6a34a6b4de4c2))
+* add version command to CLI and update documentation ([058da9c](https://github.com/seanwuapps/ai-team/commit/058da9c900ac790cea73cfec72902ec0f27a11a1))
+* update agent creation process and documentation, standardize definitions in YAML format ([e10ce27](https://github.com/seanwuapps/ai-team/commit/e10ce275d056cdf4cd0c810b7ee1b417b32f92a2))
+* update package name and description, add YAML dependency, and enhance frontmatter parsing ([d7414f2](https://github.com/seanwuapps/ai-team/commit/d7414f2bbdf5e9e2bd05f0a4b51bdac1caeb0c51))
+* update README for ai-team CLI, enhance installation and usage instructions ([25bcd33](https://github.com/seanwuapps/ai-team/commit/25bcd33348567c856d7747d18ca8306120d9e5ba))

package/README.md

@@ -168,6 +168,15 @@ ai-team doctor
 ai-team doctor --json   # machine-readable output for CI
 ```
 
+### `version`
+
+Print the installed CLI version.
+
+```bash
+ai-team version
+ai-team --version
+```
+
 ## Adding your own agents and skills
 
 The CLI never reads or modifies anything under `.agents/custom/`. Use that directory freely:

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/backend.md

@@ -0,0 +1,77 @@
+# Backend/CLI Implementation Handoff — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+From: backend-dev / cli-dev  
+To: reviewers / maintainers
+
+## Completed (MVP)
+
+- Added semantic-release stack and `release` script to `package.json`.
+- Updated `pnpm-lock.yaml` importer devDependency entries to reflect release stack additions.
+- Added `.releaserc.json` for branch `main` with plugins:
+  - commit-analyzer
+  - release-notes-generator
+  - changelog (`CHANGELOG.md`)
+  - npm publish
+  - github release
+  - git commit-back of `package.json`, `pnpm-lock.yaml`, `CHANGELOG.md`
+- Added `.github/workflows/release.yml`:
+  - trigger: push to `main`
+  - explicit permissions: `contents`, `issues`, `pull-requests` write
+  - env tokens: `GITHUB_TOKEN`, `NPM_TOKEN`
+  - preflight failure if `NPM_TOKEN` missing
+  - checkout full history + setup pnpm/node + non-frozen lockfile install + `pnpm release`
+
+## Notes / Constraints
+
+- Implementation kept to MVP scope only; no additional CI jobs or release channels were added.
+- Ensure repository secret `NPM_TOKEN` is configured before first release run.
+
+## Validation
+
+- Static validation performed by inspection of config/workflow content.
+- Runtime validation (workflow execution and publishing) requires GitHub Actions environment and repository secrets.
+
+## Code Review Remediation (blocker/major)
+
+Date: 2026-02-23
+
+### Finding status
+
+1. **[blocker] Lockfile incomplete for semantic-release graph**
+
+- Confirmed by inspection: importer `devDependencies` contains `semantic-release` and `@semantic-release/*`, while `packages:` does not contain matching resolved entries.
+- Validation evidence: searched `pnpm-lock.yaml` for `semantic-release@` and `@semantic-release/*@` package keys; none present.
+
+2. **[major] Release workflow lockfile integrity**
+
+- Not switched back to frozen mode because blocker above is unresolved.
+- Current workflow remains intentionally on `pnpm install --no-frozen-lockfile` as the minimal fallback until lockfile is regenerated.
+
+### Environment blocker (exact)
+
+- This agent session can read/edit workspace files but cannot run package-manager or git commands directly (no command-execution tool available in-session).
+- Because of that, `pnpm install` lockfile regeneration and commit creation cannot be performed from this handoff.
+
+### Minimal fallback (no added scope)
+
+Run these commands in the repository from a local shell or CI runner with write access:
+
+1. `pnpm install`
+2. `pnpm install --frozen-lockfile`
+3. `pnpm test`
+
+Then commit regenerated `pnpm-lock.yaml` and switch `.github/workflows/release.yml` install step back to:
+
+- `pnpm install --frozen-lockfile`
+
+### Exit criteria to clear blocker
+
+- `pnpm-lock.yaml` includes resolved `packages:` entries for:
+  - `semantic-release@...`
+  - `@semantic-release/changelog@...`
+  - `@semantic-release/commit-analyzer@...`
+  - `@semantic-release/git@...`
+  - `@semantic-release/github@...`
+  - `@semantic-release/npm@...`
+  - `@semantic-release/release-notes-generator@...`

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/code-review.md

@@ -0,0 +1,80 @@
+# Code Review — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+Reviewer: code-reviewer
+
+## Review Scope
+
+- `docs/agents/plans/REL-SEMVER-AUTOPUBLISH/plan.md`
+- `docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/integration.md`
+- `package.json`
+- `pnpm-lock.yaml`
+- `.releaserc.json`
+- `.github/workflows/release.yml`
+
+## Structured Findings
+
+### 1) [blocker] Lockfile is internally inconsistent for release dependencies
+
+**Where:** `pnpm-lock.yaml`  
+**What:** `importers.devDependencies` includes `semantic-release` and `@semantic-release/*`, but the lockfile has no corresponding resolved entries in `packages:` for these modules.  
+**Why it matters:** This breaks determinism and signals an incomplete lockfile regeneration. CI should fail under strict lockfile mode; current workflow masks this by disabling frozen lockfile.
+
+### 2) [major] CI workflow bypasses lockfile integrity
+
+**Where:** `.github/workflows/release.yml` (`Install dependencies` step)  
+**What:** Uses `pnpm install --no-frozen-lockfile`.  
+**Why it matters:** Allows implicit lockfile mutation during release and hides dependency drift, reducing reproducibility and increasing supply-chain risk surface.
+
+### 3) [major] Release pipeline and docs are coupled to duplicated dependency-state assumptions
+
+**Where:** `plan.md` and `integration.md`  
+**What:** Both documents carry overlapping statements about lockfile completeness/state, but only one contains unresolved caveats.  
+**Why it matters:** Duplication invites drift; operational readiness can be misread if one doc is updated and the other is not.
+
+### 4) [minor] Workflow permissions are broader than strictly required for current config intent
+
+**Where:** `.github/workflows/release.yml`  
+**What:** Grants `issues: write` and `pull-requests: write` globally.  
+**Why it matters:** Principle-of-least-privilege concern. Keep only permissions needed by the enabled behavior of `@semantic-release/github`.
+
+### 5) [minor] Toolchain versions in workflow are not pinned for deterministic release infra
+
+**Where:** `.github/workflows/release.yml`  
+**What:** Uses floating action tags and `node-version: lts/*`.  
+**Why it matters:** Reproducibility and auditability are weaker when release infra floats over time.
+
+### 6) [nit] Potentially unnecessary artifact commit in release commit-back
+
+**Where:** `.releaserc.json` (`@semantic-release/git` assets)  
+**What:** Includes `pnpm-lock.yaml` in committed assets.  
+**Why it matters:** If no dependency version changes are intended during release, lockfile churn should not happen; including it can create noisy release commits. Keep only if intentionally required by your process.
+
+## Simplification / Duplication / Maintainability / Security Summary
+
+- **Simplification:** Single source of truth for release readiness should live in one doc (prefer integration handoff), with plan doc treated as design-time baseline.
+- **Duplication:** Lockfile readiness notes are duplicated across plan/handoff narratives.
+- **Maintainability:** Reproducible release behavior requires frozen lockfile and fully regenerated lock state.
+- **Security:** Current install mode and broad permissions are avoidable risk multipliers in a release pipeline.
+
+## Explicit Action List (ordered)
+
+1. **Regenerate and commit lockfile fully**
+   - Run `pnpm install` locally and ensure `pnpm-lock.yaml` has resolved `packages:` entries for `semantic-release` + all configured plugins.
+2. **Enforce deterministic install in release job**
+   - Change release workflow install step to `pnpm install --frozen-lockfile`.
+3. **Add a pre-release integrity gate**
+   - Optionally add `pnpm install --frozen-lockfile` as a dedicated validation step before `pnpm release` to fail early and clearly.
+4. **Right-size workflow permissions**
+   - Keep only required scopes; if PR/issue comments are not needed, remove `issues: write` and `pull-requests: write`.
+5. **Reduce infra drift**
+   - Pin Node major (for example `22`) and consider pinning action SHAs for release-critical workflows.
+6. **Document ownership of readiness state**
+   - Consolidate lockfile readiness status into one canonical handoff section and reference it from plan docs to avoid drift.
+7. **Re-evaluate git commit assets**
+   - Keep `pnpm-lock.yaml` in release commit assets only if lockfile mutations are expected/desired during release operations.
+
+## QA Readiness Decision
+
+**QA should not proceed yet** (blocked) until Actions 1 and 2 are completed.  
+After those are addressed, QA can proceed with end-to-end validation from the integration test scope.

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/frontend.md

@@ -0,0 +1,22 @@
+# Frontend Handoff — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+From: frontend-dev  
+To: integration/review
+
+## Context / Objective
+
+Feature scope is release automation for npm publish and GitHub Actions. No frontend app/UI work is in scope.
+
+## What Changed
+
+N/A (no frontend code or UI changes required for this feature).
+
+## Risks / Assumptions
+
+- Assumes release automation remains backend/CI-only.
+- Assumes no docs/UI surfaces are needed to expose release status in this iteration.
+
+## Exact Next Action (Integration / Review)
+
+Proceed with backend/CI integration review only; frontend sign-off is complete with no implementation changes.

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/integration.md

@@ -0,0 +1,65 @@
+# Integration Handoff — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+From: planning-agent (integration owner)  
+To: code-reviewer / tester
+
+## 1) Combined Readiness Note
+
+- Frontend readiness: complete with no code changes required for this feature.
+- Backend/CI readiness: MVP implementation is present (`semantic-release` config + release workflow + release dependencies), with one known lockfile integrity follow-up.
+- Integration status: conditionally ready for review/test, pending dependency closure listed below.
+
+## 2) Confirmed Review Scope (Code Reviewer)
+
+Review only the release automation surface (no frontend scope):
+
+- `package.json`
+  - `release` script exists and release stack is in `devDependencies`.
+- `pnpm-lock.yaml`
+  - lock graph consistency with the newly added release dependencies.
+- `.releaserc.json`
+  - branch set to `main`.
+  - plugin order and intent:
+    1. commit analyzer
+    2. release notes generator
+    3. changelog (`CHANGELOG.md`)
+    4. npm publish
+    5. github release
+    6. git commit-back of `package.json`, `pnpm-lock.yaml`, `CHANGELOG.md`
+- `.github/workflows/release.yml`
+  - trigger on push to `main`.
+  - explicit write permissions (`contents`, `issues`, `pull-requests`).
+  - env/token wiring (`GITHUB_TOKEN`, `NPM_TOKEN`) and fail-fast check for missing `NPM_TOKEN`.
+  - install + release steps are consistent with project package manager usage.
+
+## 3) Confirmed Test Scope (Tester)
+
+Validate the following behavior end-to-end in CI:
+
+- Workflow executes on push to `main`.
+- No-op path succeeds when no semver-relevant commit is present (for example `docs:`).
+- Semver-relevant path (`fix:` / `feat:`) computes next version and performs release artifacts:
+  - npm publish,
+  - git tag,
+  - GitHub release,
+  - commit-back updates for `package.json` and `CHANGELOG.md` (and lockfile when changed).
+- Missing or invalid `NPM_TOKEN` fails with explicit/auth-related error signal.
+- Local dependency integrity checks pass after lockfile regeneration:
+  1. `pnpm install`
+  2. `pnpm install --frozen-lockfile`
+  3. `pnpm test`
+
+## 4) Explicit Unresolved Dependencies
+
+1. **Lockfile resolution completeness**
+   - Current state indicates importer devDependency references were added, but full resolved `packages:` entries for `semantic-release` and `@semantic-release/*` still require verification/regeneration.
+   - Needed action: regenerate lockfile and confirm frozen-lockfile install passes.
+2. **Repository secret availability**
+   - `NPM_TOKEN` must be configured in GitHub repository secrets prior to first release execution.
+3. **Runtime CI validation not yet executed in handoff context**
+   - End-to-end GitHub Actions run and actual npm publish flow remain pending tester execution in the target repo environment.
+
+## Integration Owner Decision
+
+Proceed to code review and tester validation with the above unresolved dependencies tracked as required completion gates before production reliance.

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/planning-agent.md

@@ -0,0 +1,67 @@
+# Planning Handoff — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+From: planning-agent  
+To: implementation agent (`backend-dev` / `cli-dev`)
+
+## Objective
+
+Implement MVP auto semantic-version publishing for `ai-team` on push to `main` using `semantic-release`, including npm publish, GitHub release/tag, and commit-back of version/changelog artifacts.
+
+## Required File Changes
+
+- `package.json`
+- `pnpm-lock.yaml`
+- `.releaserc.json` (new)
+- `.github/workflows/release.yml` (new)
+- `CHANGELOG.md` (created/updated by release)
+
+## Implementation Notes (MVP)
+
+1. Add only required semantic-release stack dependencies and a `release` script.
+2. Configure `.releaserc.json` for branch `main`, standard analyzer/notes plugins, npm publish, GitHub release, and git commit of artifacts.
+3. Use a single workflow triggered on push to `main` with explicit permissions:
+   - `contents: write`
+   - `issues: write`
+   - `pull-requests: write`
+4. Workflow auth/env must use:
+   - `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
+   - `NPM_TOKEN: ${{ secrets.NPM_TOKEN }}`
+5. Include a clear preflight check for missing `NPM_TOKEN`.
+
+## Execution Checklist
+
+- [ ] Update `package.json` with release dependencies + `release` script.
+- [ ] Update `pnpm-lock.yaml` via install.
+- [ ] Add `.releaserc.json` with plugin order and git assets (`package.json`, `pnpm-lock.yaml`, `CHANGELOG.md`).
+- [ ] Add `.github/workflows/release.yml` with push-to-main trigger, permissions, setup/install, and `pnpm release`.
+- [ ] Ensure repo secret `NPM_TOKEN` exists.
+- [ ] Validate no-op behavior with non-release commit.
+- [ ] Validate publish behavior with `fix:` or `feat:` commit.
+
+## Acceptance Mapping
+
+- AC1 (workflow on main push): workflow trigger in `.github/workflows/release.yml`.
+- AC2 (no-op success): semantic-release exits successfully when no relevant commits.
+- AC3 (publish + tag + GitHub release + commit-back): `.releaserc.json` plugins + workflow auth.
+- AC4 (missing/invalid token fails clearly): workflow preflight + semantic-release logs.
+- AC5 (no manual bump): commit-message-driven versioning only.
+
+## Failure / Rollback
+
+- If config breaks CI, revert `.releaserc.json` and `.github/workflows/release.yml` in one commit.
+- If release artifacts are incorrect, revert release commit/tag and ship corrective follow-up version.
+- If npm auth fails, rotate `NPM_TOKEN` and rerun workflow.
+
+---
+
+## Closeout Note (2026-02-23)
+
+- **Status:** Blocked (not complete).
+- **Driver:** QA decision is **BLOCKED / NOT APPROVED** pending lockfile integrity closure and runtime CI release-path validation.
+- **Required next actions:**
+  1.  Regenerate + commit `pnpm-lock.yaml` and verify semantic-release packages are fully resolved.
+  2.  Update release workflow install step to `pnpm install --frozen-lockfile`.
+  3.  Re-run CI acceptance on `main` for `docs:` no-op and `fix:`/`feat:` publish behavior.
+  4.  Confirm `NPM_TOKEN` secret and validate missing/invalid token failure paths.
+- **Closeout gate:** Feature remains open until tester returns APPROVED.

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/qa.md

@@ -0,0 +1,87 @@
+# QA Report — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+Agent: tester
+
+## Inputs Reviewed
+
+- docs/agents/plans/REL-SEMVER-AUTOPUBLISH/plan.md
+- docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/integration.md
+- docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/code-review.md
+- docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/backend.md
+- package.json
+- .releaserc.json
+- .github/workflows/release.yml
+- pnpm-lock.yaml
+
+## Verification Performed (Current Environment)
+
+- Static verification of release config, workflow trigger/permissions/token checks, and dependency declarations.
+- Lockfile integrity inspection for semantic-release package resolution entries.
+- Workspace diagnostics check (`get_errors`) returned no editor-detected errors.
+
+## Acceptance Check Results
+
+1. **Workflow runs on push to `main`**  
+   **Status:** BLOCKED (not executable in current environment)  
+   **Evidence:** Workflow exists with `on.push.branches: [main]` in `.github/workflows/release.yml`, but no GitHub Actions execution capability is available in this session.
+
+2. **No-op release succeeds when no semver-relevant commits**  
+   **Status:** BLOCKED  
+   **Evidence:** Requires an actual push (for example `docs:`) and observing workflow result; cannot be executed from this environment.
+
+3. **Semver-relevant commits publish and create artifacts (npm/tag/GitHub release/commit-back)**  
+   **Status:** BLOCKED  
+   **Evidence:** Requires live GitHub Actions + npm publish credentials and repository access. Not executable here.
+
+4. **Missing/invalid `NPM_TOKEN` fails clearly**  
+   **Status:** PARTIAL PASS (missing-token path), BLOCKED (invalid-token path)  
+   **Evidence:** `.github/workflows/release.yml` includes an explicit preflight that exits with a clear error when `NPM_TOKEN` is empty. Invalid token behavior still requires runtime execution to verify auth failure path.
+
+5. **No manual version bump required**  
+   **Status:** PARTIAL PASS (static), BLOCKED (runtime confirmation)  
+   **Evidence:** `package.json` has `"release": "semantic-release"`; `.releaserc.json` is configured for semantic-release branch/plugin flow. End-to-end confirmation requires a real `fix:`/`feat:` release run.
+
+## Additional QA Gate Checks from Integration Handoff
+
+1. `pnpm install`  
+   **Status:** BLOCKED (command execution unavailable in this session)
+2. `pnpm install --frozen-lockfile`  
+   **Status:** BLOCKED (command execution unavailable in this session)
+3. `pnpm test`  
+   **Status:** BLOCKED (command execution unavailable in this session)
+
+Static evidence indicates lockfile/workflow readiness is not yet production-safe:
+
+- `pnpm-lock.yaml` importer references include `semantic-release` and `@semantic-release/*`, but resolved `packages:` entries for those release modules are not present.
+- `.github/workflows/release.yml` currently installs with `pnpm install --no-frozen-lockfile`, which bypasses lockfile integrity.
+
+## Blockers and Exact Steps to Complete QA
+
+### Blockers
+
+1. No GitHub Actions execution / push capability in this environment.
+2. No npm publish/token validation path in this environment.
+3. No package-manager command execution available in-session for local integrity checks.
+4. Dependency lockfile state not fully regenerated for release stack; workflow currently avoids frozen lockfile.
+
+### Exact Completion Steps
+
+1. Regenerate lockfile in a shell with repo write access:
+   - `pnpm install`
+2. Validate deterministic install and tests:
+   - `pnpm install --frozen-lockfile`
+   - `pnpm test`
+3. Commit regenerated `pnpm-lock.yaml`.
+4. Update workflow install step in `.github/workflows/release.yml` to:
+   - `pnpm install --frozen-lockfile`
+5. In GitHub repository settings, ensure `NPM_TOKEN` exists and has publish scope.
+6. Execute CI acceptance runs on `main`:
+   - Push `docs:` commit and confirm successful no-op release.
+   - Push `fix:` commit and confirm npm publish, tag `vX.Y.Z`, GitHub release, and commit-back updates.
+   - Validate missing-token and invalid-token failure paths in a safe test repo/context.
+
+## Final QA Decision
+
+**Decision: BLOCKED / NOT APPROVED**  
+Reason: Core acceptance checks requiring CI runtime and publish flow are not executable in this environment, and pre-runtime dependency integrity gates (lockfile completeness + frozen lockfile install path) are not yet satisfied.

package/docs/agents/handoffs/REL-SEMVER-AUTOPUBLISH/requirement-analyst.md

@@ -0,0 +1,77 @@
+# Requirement Analysis — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+Agent: requirement-analyst
+
+## User Ask (normalized)
+
+Enable semantic versioning and a GitHub pipeline so that every push to `main` automatically determines the next version, bumps the package version, and publishes the new version of `ai-team` to npm.
+
+## MVP Scope
+
+1. Add one release workflow in `.github/workflows/` triggered on push to `main`.
+2. Use semantic versioning automation (MVP choice: `semantic-release` + npm + git/github plugins).
+3. Publish `ai-team` to npm when a release is produced.
+4. Commit version/changelog updates back to `main` as part of release automation.
+
+## Out of Scope (for this feature)
+
+- Multi-branch release channels (`beta`, `next`, etc.).
+- Monorepo/workspace package release orchestration.
+- Container/image publishing.
+- Custom changelog formatting beyond default plugin templates.
+
+## Assumptions
+
+1. `main` is the only release branch.
+2. Commit messages will follow Conventional Commits for deterministic semver bumps:
+   - `fix:` => patch
+   - `feat:` => minor
+   - `BREAKING CHANGE:` / `!` => major
+3. npm package `ai-team` already exists and is intended to remain public (`publishConfig.access=public`).
+4. Repository administrators can add required GitHub Actions permissions and repository secrets.
+
+## Required Secrets & Permissions
+
+### GitHub Repository Secrets
+
+- `NPM_TOKEN`: npm automation token with publish access to `ai-team`.
+
+### Workflow Permissions
+
+Release workflow job must grant:
+
+- `contents: write` (commit/tag/release notes/version artifacts)
+- `issues: write` and `pull-requests: write` (if release tool comments/updates PR metadata)
+
+### Optional/Conditional
+
+- `GH_TOKEN` is usually provided via `${{ secrets.GITHUB_TOKEN }}`; no extra secret needed unless org policy requires PAT.
+
+## Acceptance Criteria (implementable)
+
+1. On every push to `main`, GitHub Actions runs a release workflow.
+2. If commits since last release contain no semver-relevant changes, workflow exits successfully without publishing.
+3. If commits include semver-relevant changes:
+   - next semver version is computed from commit history,
+   - npm package `ai-team` is published,
+   - release tag (e.g. `v1.0.3`) and GitHub release are created,
+   - `package.json` version and changelog artifacts are committed back to `main`.
+4. Workflow fails with clear logs when `NPM_TOKEN` is missing/invalid.
+5. No manual version bump step is required from developers for normal releases.
+
+## Constraints for Planning/Implementation
+
+- Keep implementation minimal: one workflow file, minimal release config, only required dev dependencies/plugins.
+- Do not add unrelated CI jobs or quality gates in this feature.
+- Preserve current package metadata and existing scripts unless strictly needed for release automation.
+
+## Exact Next Action for Planning Agent
+
+Create `docs/agents/plans/REL-SEMVER-AUTOPUBLISH/plan.md` with a step-by-step implementation plan that includes:
+
+1. Adding `semantic-release` and required plugins (`@semantic-release/commit-analyzer`, `@semantic-release/release-notes-generator`, `@semantic-release/changelog`, `@semantic-release/npm`, `@semantic-release/git`, `@semantic-release/github`).
+2. Defining semantic-release config (release branch `main`, changelog + package version commit strategy).
+3. Creating `.github/workflows/release.yml` for push-to-main execution with required permissions and npm auth.
+4. Validation steps (dry-run where possible, then real run criteria) and rollback/failure handling notes.
+5. Explicit checklist mapping each implementation step back to acceptance criteria above.

package/docs/agents/knowledge/backend-dev.md

@@ -0,0 +1,7 @@
+# Backend Dev Knowledge
+
+## 2026-02-23 — REL-SEMVER-AUTOPUBLISH
+
+- Keep semantic-release MVP minimal: one `.releaserc.json` and one `push`-to-`main` workflow.
+- Include explicit workflow permissions and a preflight `NPM_TOKEN` check to fail fast with clear logs.
+- Include lockfile in git plugin assets so release commit-back stays deterministic for package metadata updates.

package/docs/agents/knowledge/code-reviewer.md

@@ -0,0 +1,7 @@
+# code-reviewer knowledge
+
+## 2026-02-23 — REL-SEMVER-AUTOPUBLISH
+
+- Treat lockfile importer-only dependency additions as a blocker when `packages:` resolutions are missing; this is incomplete dependency state, not a cosmetic diff.
+- Flag any release workflow use of `--no-frozen-lockfile` as a reproducibility/security risk unless explicitly justified for non-release jobs.
+- For release features, always verify least-privilege workflow permissions and call out duplicated readiness statements across plan and integration docs to reduce drift.

package/docs/agents/knowledge/frontend-dev.md

@@ -0,0 +1,5 @@
+# Frontend Dev Knowledge
+
+## 2026-02-23 — REL-SEMVER-AUTOPUBLISH
+
+No frontend/UI scope for this feature; frontend changes are intentionally N/A. Integration proceeds via backend/CI review only.

package/docs/agents/knowledge/planning-agent.md

@@ -0,0 +1,17 @@
+# Planning Agent Knowledge
+
+## 2026-02-23 — REL-SEMVER-AUTOPUBLISH
+
+- For semver autopublish MVPs, keep to one workflow (`push` on `main`) plus one `.releaserc.json`; avoid extra channels/gates.
+- Always include git plugin assets explicitly (`package.json`, lockfile, `CHANGELOG.md`) to satisfy commit-back acceptance criteria.
+- Add explicit token preflight in workflow to make missing `NPM_TOKEN` failures obvious and fast to diagnose.
+
+## 2026-02-23 — Integration Handoff Practice
+
+- Integration handoff should always consolidate frontend/backend readiness into one explicit go/no-go note.
+- Confirm review scope and test scope as concrete file/behavior checklists, not generic guidance.
+- Always include a dedicated unresolved dependencies list so blockers (for example secrets, lockfile integrity, runtime CI validation) are tracked to closure.
+
+## 2026-02-23 — Closeout Discipline
+
+- In closeout updates, feature status must mirror QA disposition exactly; if QA is blocked, plan/handoff status must remain blocked.

package/docs/agents/knowledge/requirement-analyst.md

@@ -0,0 +1,7 @@
+# Requirement Analyst Knowledge
+
+## 2026-02-23 — REL-SEMVER-AUTOPUBLISH
+
+- For "auto bump + publish on main" asks, define MVP as a single push-to-main release workflow using semantic-release and Conventional Commits.
+- Always capture required operational prerequisites explicitly: `NPM_TOKEN` secret and workflow write permissions (`contents` at minimum).
+- Acceptance criteria must include both publish and no-op behavior so teams can verify deterministic release outcomes.

package/docs/agents/knowledge/tester.md

@@ -0,0 +1,7 @@
+# Tester Knowledge
+
+## 2026-02-23
+
+- For release automation features, separate static-confidence checks (workflow/config correctness) from runtime-proof checks (GitHub Actions execution, publish, tags, releases) and report them independently.
+- Treat lockfile completeness + frozen-lockfile install as mandatory preconditions before declaring QA ready on CI release pipelines.
+- When environment tooling cannot execute package-manager or CI actions, include exact completion commands and the minimum external validations needed to close QA.

package/docs/agents/plans/REL-SEMVER-AUTOPUBLISH/plan.md

@@ -0,0 +1,148 @@
+# Implementation Plan — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+Agent: planning-agent
+
+## Scope (MVP)
+
+Implement minimal semantic version auto-publish for `ai-team` on pushes to `main` using `semantic-release`, with changelog + package version committed back to `main`.
+
+## Exact Files to Change (implementation phase)
+
+1. `package.json`
+   - Add release stack devDependencies.
+   - Add a release script (`"release": "semantic-release"`) for local/CI consistency.
+2. `pnpm-lock.yaml`
+   - Lockfile update from added devDependencies.
+3. `.releaserc.json` (new)
+   - Define `main` as release branch.
+   - Configure semantic-release plugins and plugin order.
+4. `.github/workflows/release.yml` (new)
+   - Push-to-main release workflow with explicit permissions and npm auth.
+5. `CHANGELOG.md` (new/managed by release process)
+   - Created/updated automatically by `@semantic-release/changelog`.
+
+## Dependency Additions (semantic-release stack)
+
+Add to `devDependencies` in `package.json`:
+
+- `semantic-release`
+- `@semantic-release/commit-analyzer`
+- `@semantic-release/release-notes-generator`
+- `@semantic-release/changelog`
+- `@semantic-release/npm`
+- `@semantic-release/git`
+- `@semantic-release/github`
+
+No additional runtime dependencies.
+
+## Semantic-Release Config Approach
+
+Use one repo-root config file: `.releaserc.json`.
+
+Proposed MVP config:
+
+- `branches`: `["main"]`
+- `tagFormat`: `"v${version}"`
+- `plugins` in this order:
+  1. `@semantic-release/commit-analyzer`
+  2. `@semantic-release/release-notes-generator`
+  3. `@semantic-release/changelog` with `changelogFile: "CHANGELOG.md"`
+  4. `@semantic-release/npm` with `npmPublish: true`
+  5. `@semantic-release/github`
+  6. `@semantic-release/git` with assets:
+     - `package.json`
+     - `pnpm-lock.yaml`
+     - `CHANGELOG.md`
+       and message pattern:
+     - `chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}`
+
+Why this approach (minimal):
+
+- Single declarative config file.
+- Keeps release behavior explicit and reproducible.
+- Ensures changelog/version updates are committed after publish.
+
+## GitHub Actions Workflow Details
+
+Workflow file: `.github/workflows/release.yml`
+
+Trigger:
+
+- `on.push.branches: [main]`
+
+Job permissions (explicit):
+
+- `contents: write` (tags + release commit + GitHub release)
+- `issues: write` (plugin capability)
+- `pull-requests: write` (plugin capability)
+
+Auth and environment:
+
+- `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
+- `NPM_TOKEN: ${{ secrets.NPM_TOKEN }}`
+- Add preflight step: fail fast if `NPM_TOKEN` missing.
+- Node setup with npm registry URL and pnpm install using lockfile (`pnpm install --frozen-lockfile`).
+
+Minimal job steps:
+
+1. `actions/checkout` with full history (`fetch-depth: 0`)
+2. `pnpm/action-setup`
+3. `actions/setup-node` (Node LTS + npm registry)
+4. Install deps (`pnpm install --frozen-lockfile`)
+5. Run release (`pnpm release`)
+
+## Step-by-Step Execution Checklist
+
+1. Add release dependencies and script in `package.json`.
+2. Install deps to update `pnpm-lock.yaml`.
+3. Add `.releaserc.json` with branch/plugins configuration.
+4. Add `.github/workflows/release.yml` with trigger/permissions/auth.
+5. Confirm repository secret `NPM_TOKEN` is configured.
+6. Merge to `main` with a Conventional Commit (`feat:` or `fix:`) to validate end-to-end.
+
+## Acceptance Checks Mapped to Requirement Criteria
+
+1. **Workflow runs on push to main**
+   - Check Actions tab shows `release` workflow for a `main` push.
+2. **No-op release succeeds when no semver-relevant commits**
+   - Push commit such as `docs: ...`; verify workflow exits success with "no release" behavior.
+3. **Semver-relevant commits publish and create release artifacts**
+   - Push `fix:` and verify:
+     - computed next version,
+     - npm package published,
+     - git tag `vX.Y.Z` exists,
+     - GitHub release created,
+     - commit back to `main` includes `package.json` + `CHANGELOG.md` (+ lockfile if updated).
+4. **Missing/invalid NPM_TOKEN fails clearly**
+   - Temporarily remove/rotate invalid secret in test repo; verify release job fails with explicit auth/preflight error.
+5. **No manual version bump required**
+   - Verify release succeeds from commit messages only without editing `version` manually.
+
+## Rollback / Failure Notes
+
+1. If publish fails before git commit step:
+   - Fix token/permissions and rerun workflow; no repo file rollback needed.
+2. If git release commit is undesirable:
+   - Revert release commit on `main` and delete erroneous tag/release in GitHub.
+3. If wrong version was published to npm:
+   - Do **not** unpublish stable versions broadly; publish a corrective next version and document in changelog.
+4. If semantic-release config causes repeated failures:
+   - Revert `.releaserc.json` and `.github/workflows/release.yml` via a single rollback commit to restore previous non-automated state.
+
+## Out-of-Scope Guardrails
+
+- No multi-branch channels.
+- No monorepo/workspace release orchestration.
+- No extra CI jobs/quality gates added in this feature.
+
+## Closeout Status (2026-02-23)
+
+- **Current state:** **Blocked (QA not approved)**.
+- **Why blocked:** QA handoff reports end-to-end acceptance is blocked by unresolved lockfile integrity and unavailable runtime CI/publish validation in current environment.
+- **Completion criteria to close feature:**
+  1.  Regenerate and commit `pnpm-lock.yaml` with full semantic-release dependency resolution.
+  2.  Enforce deterministic install in `.github/workflows/release.yml` using `pnpm install --frozen-lockfile`.
+  3.  Execute CI validation on `main` for no-op (`docs:`) and release (`fix:`/`feat:`) paths.
+  4.  Verify `NPM_TOKEN` secret presence and confirm missing/invalid token failure behavior.
+- **Planning decision:** Do not mark feature complete until QA re-runs and returns APPROVED.

package/docs/cli.md

@@ -8,6 +8,7 @@
 - `ai-team update` — apply bundled template updates with drift protection
 - `ai-team plan` (or `diff`) — dry-run preview
 - `ai-team doctor` — validate manifest health and local drift
+- `ai-team version` (or `--version`) — print installed CLI version
 
 ## Runtime Profile
 

package/package.json

@@ -1,29 +1,38 @@
 {
   "name": "ai-team",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "AI agent team management CLI tool",
   "type": "module",
   "main": "src/cli.js",
   "bin": {
     "ai-team": "src/cli.js"
   },
+  "scripts": {
+    "test": "node --test",
+    "ai-team": "node ./src/cli.js",
+    "release": "semantic-release"
+  },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "pnpm@10.28.1",
   "dependencies": {
-    "@inquirer/prompts": "^8.2.1",
+    "@inquirer/prompts": "^8.3.0",
     "chalk": "^5.6.2",
     "ora": "^9.3.0",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "mustache": "^4.2.0"
-  },
-  "scripts": {
-    "test": "node --test",
-    "ai-team": "node ./src/cli.js"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "mustache": "^4.2.0",
+    "semantic-release": "^25.0.3"
   }
-}
+}

package/src/cli.js

@@ -19,8 +19,10 @@ Commands:
   plan      Dry-run preview of changes
   diff      Alias of plan
   doctor    Validate install health and report drift
+  version   Print installed CLI version
 
 Options:
+  -v, --version             Print installed CLI version
   --ide <vscode|claude-code>
   --team <web-product>
   --target <path>           Default: current directory
@@ -33,6 +35,12 @@ Options:
 `);
 }
 
+async function printVersion() {
+  const packageJsonPath = new URL("../package.json", import.meta.url);
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  console.log(packageJson.version);
+}
+
 function createSpinner(values, text) {
   const canUseSpinner = !values.json && process.stdout.isTTY;
   return ora({ text, isEnabled: canUseSpinner }).start();
@@ -272,6 +280,11 @@ function asJson(values, payload) {
 
 async function run() {
   const [, , commandArg] = process.argv;
+  if (["version", "--version", "-v"].includes(commandArg)) {
+    await printVersion();
+    process.exit(0);
+  }
+
   const command = commandArg === "diff" ? "plan" : commandArg;
 
   if (!command || ["-h", "--help", "help"].includes(command)) {

package/tests/cli.integration.test.js

@@ -61,3 +61,18 @@ test("cli init and doctor succeed in temp repo", async () => {
   assert.equal(doctorResult.code, 0, doctorResult.stderr);
   assert.match(doctorResult.stdout, /Doctor: OK/);
 });
+
+test("cli prints package version", async () => {
+  const workspaceRoot = path.resolve(process.cwd());
+  const packageJson = JSON.parse(
+    await fs.readFile(path.join(workspaceRoot, "package.json"), "utf8"),
+  );
+
+  const versionResult = await runCli(["version"], workspaceRoot);
+  assert.equal(versionResult.code, 0, versionResult.stderr);
+  assert.equal(versionResult.stdout.trim(), packageJson.version);
+
+  const flagResult = await runCli(["--version"], workspaceRoot);
+  assert.equal(flagResult.code, 0, flagResult.stderr);
+  assert.equal(flagResult.stdout.trim(), packageJson.version);
+});