ai-team 1.0.2 → 1.2.0

package/.agents/teams/web-product/README.md

@@ -27,7 +27,7 @@ Generated install targets (VS Code):
 
 - Agent templates: `src/agents/definitions/*.yaml`
 - Template pack metadata: `templates/bootstrap/manifest.json`
-- Bootstrap overlays: `templates/bootstrap/overlays/**`
+- Generated preview output: `templates/bootstrap/base/.agents/generated/agents/**`
 - Product direction: `docs/prd.md`
 - Delivery state: `docs/PROGRESS.md`
 - User stories: `docs/stories/*.md`

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,39 @@
+# [1.2.0](https://github.com/seanwuapps/ai-team/compare/v1.1.0...v1.2.0) (2026-02-23)
+
+
+### Features
+
+* Remove IDE overlay agents and shift to generation-driven outputs ([4b29d63](https://github.com/seanwuapps/ai-team/commit/4b29d6342c49b02acca9f88ffcc920af728d089e))
+
+# [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/README.md

@@ -22,7 +22,8 @@ This directory tracks agent workflow artifacts used during delivery.
 ## Template Source of Truth
 
 - Canonical agent template definitions: `src/agents/definitions/*.yaml`
-- Template metadata and overlay routing: `templates/bootstrap/manifest.json`
+- Template metadata and IDE path routing: `templates/bootstrap/manifest.json`
+- Generated preview output (for maintenance): `templates/bootstrap/base/.agents/generated/agents/**`
 - Generated install targets: `.github/agents/*.agent.md` and `.claude/agents/*.md`
 
 ## Documentation Writer Usage

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/backend.md

@@ -0,0 +1,100 @@
+# Backend Handoff — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: backend-dev
+
+## Context/objective
+
+Implement REL-NO-IDE-OVERLAYS by removing runtime dependency on committed per-IDE overlay agent files and making agent installation resolve from generated content derived from `src/agents/definitions/*.yaml`.
+
+## What changed
+
+1. Generation/runtime integration
+   - Refactored `src/agents/generate.js` into reusable generation logic with exported `generateAgentEntriesForIde(...)`.
+   - Kept IDE-specific output parity behavior (filename/frontmatter/body rendering) while adding direct-CLI generation output under `templates/bootstrap/base/.agents/generated/agents/<ide>/`.
+
+2. Template resolution and manifest routing
+   - Updated `src/lib/template-registry.js` to source agent entries from generated content instead of reading overlay agent files from disk.
+   - Updated `templates/bootstrap/manifest.json` from `packs.overlays` to `packs.ide`, removed overlay root coupling, and added `mcpTemplate` locations.
+   - Moved MCP templates into base template assets:
+     - `templates/bootstrap/base/.agents/mcp/vscode.json`
+     - `templates/bootstrap/base/.agents/mcp/claude-code.json`
+
+3. Docs and contract updates
+   - Updated docs to describe generation-driven source-of-truth and remove overlay routing language where applicable:
+     - `docs/cli.md`
+     - `docs/plan.md`
+     - `docs/agents/README.md`
+     - `.agents/teams/web-product/README.md`
+     - `templates/bootstrap/base/.agents/teams/web-product/README.md`
+   - Updated `src/agents/definitions/agent-manager.yaml` language to reference generated outputs instead of overlay regeneration.
+
+4. Test coverage updates
+   - `tests/sync-engine.test.js`:
+     - added assertions for generated source paths (`.generated/agents/...`) and claude-code target mapping (`.claude/agents/*.md`, `.mcp.json`).
+   - `tests/cli.integration.test.js`:
+     - added claude-code init+doctor coverage.
+
+5. Dependency alignment
+   - Moved `mustache` to runtime dependencies in `package.json` since generation logic is now used during runtime template collection.
+
+## Risks/assumptions
+
+- Assumes `packs.ide` manifest shape is acceptable for this release line (no strict backward parser dependence on `packs.overlays`).
+- Existing local installs may see planned updates due source path metadata and generated-content source hashes.
+- Overlay folder cleanup was partially constrained by workspace tooling behavior for file deletion; runtime no longer depends on overlay content.
+
+## Validation
+
+- Static diagnostics (`get_errors`) on changed implementation and test files: **no errors**.
+- Targeted test command: **not executed in this environment** (no terminal execution tool available in current agent toolset).
+- Broader test command: **not executed in this environment** (same limitation).
+
+## Fix pass (2026-02-23)
+
+Resolved items from code-review + integration handoffs:
+
+1. BLOCKER — prevent MCP templates from base asset copy
+   - Updated `src/lib/template-registry.js` to exclude `.agents/mcp/*` from recursive base copy entries.
+   - MCP output behavior is preserved through explicit `json-merge` entries targeting:
+     - `.vscode/mcp.json` for vscode
+     - `.mcp.json` for claude-code
+
+2. MAJOR — manifest transition compatibility (`packs.overlays` → `packs.ide`)
+   - Added compatibility shim in runtime template resolution (`src/lib/template-registry.js`) to accept either shape.
+   - Added compatibility shim in generation path (`src/agents/generate.js`) to accept either shape.
+   - Added explicit fallback for MCP template resolution when legacy manifests omit `mcpTemplate`.
+
+3. MAJOR — remove legacy overlay artifacts from repository
+   - Runtime is fully decoupled from `templates/bootstrap/overlays/**`.
+   - Repository file deletion was attempted via available patch tooling, but deletions did not persist in this environment (files remain present in working tree).
+
+4. Test additions for blocker + compatibility
+   - Added `tests/template-registry.test.js` covering:
+     - exclusion of `.agents/mcp/*` from copied entries,
+     - MCP target presence only when `includeMcp` is enabled,
+     - legacy `packs.overlays` compatibility in `getIdePack(...)`.
+
+### Latest validation outcomes (fix pass)
+
+- Static diagnostics (`get_errors`) on changed files: no errors.
+- Targeted tests requested:
+  - `node --test tests/template-registry.test.js`
+  - `node --test tests/sync-engine.test.js`
+  - `node --test tests/cli.integration.test.js`
+  - **Status:** not executable in current tool-constrained environment (no command runner available).
+- Broader tests requested:
+  - `pnpm test`
+  - **Status:** not executable in current tool-constrained environment (no command runner available).
+
+## Exact next action for integration handoff
+
+Run and capture the following commands in CI or a local shell with repo write/test access, then attach output to the integration handoff:
+
+1. `node --test tests/sync-engine.test.js`
+2. `node --test tests/cli.integration.test.js`
+3. `pnpm test`
+
+## Cleanup note (overlay repository removal)
+
+Attempted explicit deletion of every file under `templates/bootstrap/overlays/**` via available patch tooling; in this environment those operations are applied as in-place edits rather than physical removals, so overlay files/directories still exist and cleanup remains pending execution in a shell with direct filesystem delete support.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/code-review.md

@@ -0,0 +1,83 @@
+# Code Review — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: code-reviewer
+
+## Gate
+
+**Overall QA gate: FAIL**
+
+Reason: one blocker must be fixed before QA pass.
+
+## Review coverage
+
+- Inputs reviewed:
+  - `docs/agents/plans/REL-NO-IDE-OVERLAYS/plan.md`
+  - `docs/agents/handoffs/REL-NO-IDE-OVERLAYS/integration.md`
+- Changed implementation/docs reviewed from working tree, with focus on:
+  - `src/agents/generate.js`
+  - `src/lib/template-registry.js`
+  - `templates/bootstrap/manifest.json`
+  - `package.json`
+  - `tests/sync-engine.test.js`
+  - `tests/cli.integration.test.js`
+  - related docs updates
+
+## Findings
+
+### simplification
+
+1. **[minor] Legacy overlay naming remains in runtime adapter API**
+   - `applyOverlay()` and related call sites still use overlay terminology even after architecture shifted to generation-driven `packs.ide`.
+   - Impact: conceptual debt and future confusion for contributors; not functionally blocking.
+
+### duplication
+
+1. **[major] Three parallel agent sources are still present in repo**
+   - Agent content now exists across:
+     - source definitions (`src/agents/definitions/*.yaml`),
+     - generated preview output (`templates/bootstrap/base/.agents/generated/agents/**`),
+     - legacy overlay agent files (`templates/bootstrap/overlays/**`).
+   - Impact: high drift risk and ambiguous maintenance source, contradicting “single maintained source” intent.
+
+### maintainability
+
+1. **[blocker] MCP templates under base assets are unintentionally included as normal copied files**
+   - New files under `templates/bootstrap/base/.agents/mcp/*.json` are now inside the base recursive copy root.
+   - `collectTemplateEntries()` currently copies all base files, so installs can include `.agents/mcp/vscode.json` and `.agents/mcp/claude-code.json` in downstream projects, which is outside documented layout contract.
+   - Impact: behavioral contract regression (unexpected installed files), potential drift noise, and avoidable template surface expansion.
+
+2. **[major] Manifest compatibility transition lacks explicit backward-compatibility guardrails**
+   - Runtime now relies on `manifest.packs.ide` and no longer on `packs.overlays`.
+   - No compatibility shim or assertion path for mixed/older manifest structures is present.
+   - Impact: brittle behavior if template schema consumers or automation still assume legacy shape.
+
+3. **[minor] Overlay cleanup is incomplete and currently documented as partial**
+   - Legacy overlay files still remain in repository, including agent files and MCP placeholders.
+   - Impact: continued confusion during maintenance; non-blocking if runtime independence is preserved.
+
+### security
+
+1. **[minor] MCP merge logic remains schema-specific to `servers` and is not validated for Claude `mcpServers` evolution**
+   - Merge routine is keyed to `servers` semantics; claude template currently uses `mcpServers`.
+   - Impact: if security-relevant MCP defaults change later for claude, update/merge behavior may not propagate as intended.
+
+## Explicit action list
+
+### Must fix before QA pass
+
+1. Fix template entry collection so base MCP template files are **not** installed as normal `.agents/mcp/*` copy artifacts (or relocate templates outside base recursive copy root with equivalent behavior).
+
+### Should fix in this feature cycle
+
+2. Define and implement explicit compatibility handling for `packs.overlays` → `packs.ide` transition (either migration path or deliberate fail-fast with clear message).
+3. Remove/retire remaining overlay agent artifacts to eliminate multi-source drift and align with feature objective.
+
+### Can fix shortly after
+
+4. Rename overlay-era API terminology (`applyOverlay`) to ide-focused naming for clarity.
+5. Add/extend tests for claude MCP merge semantics to ensure future template updates merge predictably.
+
+## QA disposition statement
+
+QA **must not pass** this feature until the blocker above is resolved and re-validated with targeted tests plus full suite evidence.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/frontend.md

@@ -0,0 +1,24 @@
+# Frontend Handoff — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: frontend-dev
+
+## Context and objective
+
+Review REL-NO-IDE-OVERLAYS for frontend impact and provide handoff status. Feature scope is backend-only (CLI/template-registry/sync-engine/docs architecture updates), so frontend implementation is **N/A**.
+
+## What changed / what remains
+
+- Frontend implementation changes: **N/A**.
+- No Vue/UI/frontend runtime files were modified for this feature.
+- No frontend tests or UI validation are required for this scope.
+- Remaining work on this feature stays with backend/integration agents.
+
+## Risks and assumptions
+
+- Assumes feature boundaries remain backend-only and do not introduce new UI/runtime surfaces.
+- If scope expands to user-facing frontend behavior, a new frontend implementation pass will be required.
+
+## Exact next action for receiving agent
+
+Proceed with backend/integration validation and release handoff; treat frontend implementation as closed with status **N/A** for REL-NO-IDE-OVERLAYS.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/integration.md

@@ -0,0 +1,51 @@
+# Integration Handoff — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+From: planning-agent (integration owner)  
+To: code-reviewer / tester
+
+## Context and objective
+
+REL-NO-IDE-OVERLAYS removes runtime dependence on committed per-IDE overlay agent files by sourcing installable agent content from generated outputs derived from `src/agents/definitions/*.yaml`, while preserving CLI behavior for `init`, `plan`, `update`, and `doctor` across `vscode` and `claude-code`.
+
+## Combined readiness note (frontend/backend)
+
+- Frontend readiness: **N/A / complete** for this feature scope (no frontend implementation changes required).
+- Backend readiness: implementation and test updates are present, including generation/runtime integration, manifest routing updates, docs alignment, and test file updates.
+- Integration readiness: **conditionally ready** for review/test.
+- Test execution evidence: **missing in current artifacts** (backend handoff explicitly states tests were not executed in this environment).
+
+## Review scope checklist for code-reviewer
+
+- [ ] Verify generation/runtime path change is intentional and complete:
+  - `src/agents/generate.js` exports reusable generation API for IDE entries.
+  - `src/lib/template-registry.js` sources IDE agent entries from generated content, not committed overlay agent files.
+- [ ] Verify manifest contract updates are coherent and safe:
+  - `templates/bootstrap/manifest.json` uses `packs.ide` and includes `mcpTemplate` mapping.
+- [ ] Verify runtime dependency alignment:
+  - `package.json` includes `mustache` in runtime `dependencies` (not only dev dependencies).
+- [ ] Verify docs reflect architecture change and no longer describe committed overlay agent files as operational source.
+- [ ] Verify no unintended frontend/UI scope expansion.
+
+## Test scope checklist for tester
+
+- [ ] Run targeted sync-engine test coverage:
+  - `node --test tests/sync-engine.test.js`
+- [ ] Run targeted CLI integration coverage:
+  - `node --test tests/cli.integration.test.js`
+- [ ] Run broader regression suite:
+  - `pnpm test`
+- [ ] Validate behavior parity for both IDEs from test evidence/logs:
+  - install target paths remain correct (`.github/agents/*.agent.md`, `.claude/agents/*.md`),
+  - MCP targets remain correct (`.vscode/mcp.json`, `.mcp.json`),
+  - drift/conflict semantics for `plan`/`update`/`doctor` remain unchanged.
+
+## Explicit unresolved dependencies
+
+1. Missing test execution evidence in current handoff artifacts (targeted and full test commands are still pending execution evidence).
+2. Manifest shape transition (`packs.overlays` → `packs.ide`) requires reviewer confirmation that no downstream parser/consumer depends on legacy shape.
+3. Overlay repository cleanup is still unresolved: explicit deletion attempts via available patch tooling were applied as file edits (not physical removals), so `templates/bootstrap/overlays/**` remains present and must be deleted in an environment with direct filesystem delete support.
+
+## Exact next action for Code Reviewer
+
+Open the PR/diff for REL-NO-IDE-OVERLAYS and complete a focused review of `src/lib/template-registry.js`, `src/agents/generate.js`, and `templates/bootstrap/manifest.json` first, explicitly confirming generation-driven sourcing and manifest compatibility before broader file review.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/planning-agent.md

@@ -0,0 +1,51 @@
+# Planning Handoff — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+From: planning-agent  
+To: implementation agents (`backend-dev`, `frontend-dev`)
+
+## Objective
+
+Eliminate committed IDE overlay agent files as a maintained dependency and shift template install resolution to generation-driven IDE artifacts, while preserving current CLI behavior and output contracts.
+
+## Plan Summary
+
+- Runtime/template resolution currently reads agent files directly from `templates/bootstrap/overlays/*`.
+- Implementation should route agent entry generation through shared definition rendering (`src/agents/definitions/*.yaml`) and feed those generated outputs into template collection.
+- Existing sync safety model (hash tracking, conflict skip, MCP merge) must remain unchanged from user perspective.
+- Documentation must be updated to reflect generation-driven architecture and remove overlay-maintenance language.
+
+## Work Split
+
+### Backend Agent (`backend-dev`) — Primary Owner
+
+1. Refactor/extend generator logic so it is consumable by runtime/template registry without relying on committed overlay agent files.
+2. Update `src/lib/template-registry.js` to source IDE agent entries from generation path and retain MCP/base asset behavior.
+3. Make minimal `templates/bootstrap/manifest.json` changes needed to preserve IDE target mapping while dropping committed overlay-agent dependency.
+4. Adjust tests (`tests/sync-engine.test.js`, `tests/cli.integration.test.js`) to validate parity and unchanged sync semantics.
+5. Update `README.md` and `docs/cli.md` for architecture/source-of-truth wording.
+
+### Frontend Agent (`frontend-dev`) — N/A
+
+- **Status:** Not required for this feature.
+- **Rationale:** Scope is CLI/template-registry/sync-engine backend behavior and repository documentation; no product UI, Vue components, or frontend runtime surfaces are impacted.
+
+## Definition of Done for Implementation
+
+1. Overlay agent files are no longer required as committed runtime sources.
+2. `init`, `plan`, `update`, and `doctor` behavior remains functionally equivalent for both IDEs.
+3. MCP output paths and merge semantics remain unchanged.
+4. Tests cover generated-agent sourcing and pass in CI.
+5. Docs are updated to describe the new architecture.
+
+## Risks / Unknowns
+
+1. Potential rendering parity drift (frontmatter/whitespace) causing widespread hash updates.
+2. Manifest shape edits may unintentionally impact compatibility with existing installed manifests.
+3. Overlay removal sequencing must avoid temporary broken state where neither generated nor file-backed sources exist.
+
+## Required Next Actions
+
+1. Backend agent implements generation-backed template entry sourcing behind existing CLI contracts.
+2. Backend agent removes committed overlay agent files only after parity checks pass.
+3. Backend agent runs tests and provides implementation handoff with explicit parity evidence for both IDEs and MCP behavior.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/qa.md

@@ -0,0 +1,87 @@
+# QA Report — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: tester
+
+## Scope
+
+Inputs validated:
+
+- `docs/agents/plans/REL-NO-IDE-OVERLAYS/plan.md`
+- `docs/agents/handoffs/REL-NO-IDE-OVERLAYS/integration.md`
+- `docs/agents/handoffs/REL-NO-IDE-OVERLAYS/code-review.md`
+- Latest working tree changes
+
+## Environment limitation
+
+Command execution is unavailable in this agent environment (no terminal command runner in available toolset), so execution-dependent checks are marked **BLOCKED** with exact commands to run.
+
+## Test evidence
+
+### Static evidence collected (non-execution)
+
+1. Working-tree diffs show architecture changes aligned to feature intent:
+   - generation-driven entries in `src/agents/generate.js`
+   - template collection from generated entries in `src/lib/template-registry.js`
+   - manifest IDE routing in `templates/bootstrap/manifest.json`
+   - test additions in `tests/sync-engine.test.js`, `tests/cli.integration.test.js`, `tests/template-registry.test.js`
+2. Diagnostics check (`get_errors`) on changed implementation/tests:
+   - `src/lib/template-registry.js` — no errors
+   - `src/agents/generate.js` — no errors
+   - `tests/template-registry.test.js` — no errors
+   - `tests/sync-engine.test.js` — no errors
+   - `tests/cli.integration.test.js` — no errors
+3. Repository diff still includes `templates/bootstrap/overlays/**` content in working tree (cleanup objective remains not fully proven by deletion in this environment).
+
+### Execution-dependent evidence (blocked)
+
+Required commands to complete QA:
+
+1. `node --test tests/template-registry.test.js`
+2. `node --test tests/sync-engine.test.js`
+3. `node --test tests/cli.integration.test.js`
+4. `pnpm test`
+5. `node src/cli.js init --target /tmp/rel-no-ide-overlays-vscode --ide vscode --team web-product --include-mcp --yes`
+6. `node src/cli.js doctor --target /tmp/rel-no-ide-overlays-vscode`
+7. `node src/cli.js init --target /tmp/rel-no-ide-overlays-claude --ide claude-code --team web-product --include-mcp --yes`
+8. `node src/cli.js doctor --target /tmp/rel-no-ide-overlays-claude`
+9. Drift semantics checks:
+   - Edit installed agent file under `.github/agents/` or `.claude/agents/`
+   - `node src/cli.js plan --target <target>`
+   - `node src/cli.js update --target <target>`
+   - `node src/cli.js update --target <target> --force`
+
+## Acceptance area status
+
+1. **No committed overlay agents required** — **FAIL**
+   - Reason: Runtime appears decoupled in code, but acceptance explicitly requires proving tests pass with overlay agents removed; this was not executed in this environment.
+
+2. **Generated output parity — vscode** — **BLOCKED**
+   - Static indicators exist (generated-entry mapping and tests), but init/install parity was not executed.
+
+3. **Generated output parity — claude-code** — **BLOCKED**
+   - Static indicators exist (claude integration test added), but init/install parity was not executed.
+
+4. **Sync behavior unchanged (`plan`/`update` safe mode + `--force`)** — **BLOCKED**
+   - Requires live file edit + CLI execution evidence.
+
+5. **Doctor behavior unchanged** — **BLOCKED**
+   - Requires `doctor` command execution on initialized targets.
+
+6. **MCP path handling retained** — **BLOCKED**
+   - Static code supports `.vscode/mcp.json` and `.mcp.json`, but runtime merge/install behavior not executed.
+
+7. **Docs aligned** — **PASS (static)**
+   - `README.md`/`docs/cli.md` updates reflect generation-driven approach and multi-IDE path contract.
+
+## Visual/layout notes
+
+N/A (CLI/backend feature; no UI surface specified for visual validation).
+
+## Overall QA decision
+
+**FAIL** (execution evidence missing for core acceptance checks; several areas remain blocked).
+
+## Exact next action
+
+Run the nine commands listed in **Execution-dependent evidence (blocked)**, capture stdout/stderr, and update this QA report with command outputs and final pass/fail re-evaluation per acceptance area.

package/docs/agents/handoffs/REL-NO-IDE-OVERLAYS/requirement-analyst.md

@@ -0,0 +1,75 @@
+# Requirement Analysis — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: requirement-analyst
+
+## Context and objective
+
+Current template structure maintains IDE-specific agent artifacts under `templates/bootstrap/overlays/*` and syncs those files into target projects based on selected IDE.
+
+Observed constraints from current implementation:
+
+- `templates/bootstrap/manifest.json` defines `overlayRoot` and per-IDE overlay roots/paths (`vscode`, `claude-code`).
+- `src/agents/generate.js` generates agent files directly into overlay directories and assumes both overlays exist.
+- `src/lib/template-registry.js` resolves install entries by reading base files plus overlay files selected by IDE.
+- `src/lib/sync-engine.js` is coupled to registry output and profile IDE selection.
+- `README.md` documents per-IDE installed output paths and overlay-backed behavior.
+
+Objective: stop maintaining committed per-IDE overlay agent files and shift to generation-driven IDE output selection while preserving current user-facing `init`/`plan`/`update`/`doctor` behavior.
+
+## Scope in/out
+
+### In scope
+
+1. Remove overlay folder usage as the maintained source of agent files.
+2. Make generation the source for IDE-specific agent outputs from shared definitions.
+3. Keep CLI install/update semantics intact for both supported IDE targets.
+4. Update template manifest and docs to reflect non-overlay architecture.
+
+### Out of scope
+
+1. Adding new IDEs or changing current IDE flag names.
+2. Changing agent content semantics beyond what is required for overlay removal.
+3. Redesigning manifest tracking model (`.agents/manifest.json`) or conflict policy.
+4. Introducing new commands or workflow UX changes.
+
+## Functional requirements
+
+1. **Single maintained source**: Agent definitions in `src/agents/definitions/*.yaml` remain the single maintained source for IDE-specific agent artifacts.
+2. **No committed IDE overlay agents**: Repository must not require committed IDE-specific agent files under `templates/bootstrap/overlays/*` for normal operation.
+3. **Generation parity**: Generation process must produce equivalent IDE-specific output artifacts (file names, frontmatter shape, and body rendering) for both `vscode` and `claude-code`.
+4. **Registry compatibility**: Template entry collection must continue to provide IDE-correct target paths and content to sync logic without depending on committed overlay files.
+5. **Sync behavior unchanged**: `plan`, `update`, and `doctor` must retain existing conflict detection and copy/merge behavior from the user perspective.
+6. **MCP handling retained**: IDE-specific MCP output behavior (`.vscode/mcp.json` vs `.mcp.json`) must remain supported.
+7. **Documentation alignment**: README and relevant docs must describe generation-driven IDE outputs and remove references that imply maintained overlay folders.
+
+## Non-functional constraints
+
+1. Keep implementation minimal and backward-compatible with existing CLI flags and profile shape (`ide`, `team`, `includeMcp`, `agents`).
+2. Do not introduce runtime network dependency for generation.
+3. Preserve deterministic outputs so hash-based sync and drift detection remain reliable.
+4. Avoid broad refactors outside overlay-removal path.
+
+## Risks/assumptions
+
+### Assumptions
+
+1. Only two IDE adapters remain in scope: `vscode` and `claude-code`.
+2. Existing YAML definitions already contain enough IDE-specific metadata/body data to generate both formats.
+3. Team/base assets under `templates/bootstrap/base` remain unchanged as the non-IDE-specific template source.
+
+### Risks
+
+1. Path/filename parity regressions could trigger unnecessary overwrite actions during update.
+2. Any divergence between generated output and current committed overlay content may create apparent drift for existing users.
+3. Manifest schema references to overlays may need careful migration to avoid breaking older installs.
+
+## Exact next action for Planning Agent
+
+Create `docs/agents/plans/REL-NO-IDE-OVERLAYS/plan.md` with a minimal implementation plan that explicitly sequences:
+
+1. Source-of-truth redesign (remove committed overlay dependency while preserving IDE outputs).
+2. Manifest/template-registry updates to resolve IDE entries from generated content.
+3. Generation pipeline updates (inputs, output location strategy, and integration point with sync collection).
+4. Compatibility/migration approach for existing installs and manifest expectations.
+5. Validation checklist mapping each functional requirement above to concrete verification steps (including `plan`, `update`, `doctor` behavior and MCP paths).