ai-team 1.0.0

package/templates/bootstrap/base/.agents/skills/front-end-development/references/styling.md

@@ -0,0 +1,226 @@
+# Styling Standards
+
+## CSS Units and Values
+
+**CRITICAL RULES:**
+
+- ❌ **NO magic numbers** - Use existing design tokens when available; when creating reusable components, define component-specific tokens; otherwise, direct `rem` values are allowed
+- ❌ **NO `px` units** - Always use `rem` for scalability and accessibility
+- ❌ **NO arbitrary colors** - Only use Nuxt UI CSS variables
+
+## Nuxt UI CSS Variables
+
+This project uses **Nuxt UI** which provides theme-aware CSS variables. All colors MUST use these variables:
+
+**Text Colors:**
+
+```css
+/* ❌ WRONG - Arbitrary color values or old framework variables */
+.component {
+  color: #ffffff;
+  color: var(--p-text-color); /* Old PrimeVue variable */
+  color: rgba(255, 255, 255, 0.85);
+}
+
+/* ✅ CORRECT - Nuxt UI CSS variables */
+.component {
+  color: var(--ui-text); /* Primary text */
+  color: var(--ui-text-muted); /* Secondary/muted text */
+  color: var(--ui-text-dimmed); /* Dimmed/tertiary text */
+  color: var(--ui-text-highlighted); /* Highlighted text */
+}
+```
+
+**Background Colors:**
+
+```css
+/* ❌ WRONG */
+.component {
+  background: #1a1a1a;
+  background: var(--surface-card); /* Old variable */
+}
+
+/* ✅ CORRECT - Nuxt UI CSS variables */
+.component {
+  background: var(--ui-bg); /* Base background */
+  background: var(--ui-bg-elevated); /* Elevated surfaces (cards, modals) */
+  background: var(--ui-bg-accented); /* Accented/muted background */
+  background: var(--ui-bg-inverted); /* Inverted background */
+}
+```
+
+**Border Colors:**
+
+```css
+/* ❌ WRONG */
+.component {
+  border: 1px solid #333333;
+  border: 1px solid var(--surface-border); /* Old variable */
+}
+
+/* ✅ CORRECT - Nuxt UI CSS variables */
+.component {
+  border: 1px solid var(--ui-border); /* Standard border */
+  border: 1px solid var(--ui-border-accented); /* Accented/hover border */
+  border: 1px solid var(--ui-border-inverted); /* Inverted border */
+}
+```
+
+**Theme Colors:**
+
+```css
+/* ❌ WRONG */
+.component {
+  color: var(--p-primary-color); /* Old PrimeVue variable */
+  background: rgba(212, 255, 0, 0.1); /* Hardcoded primary */
+}
+
+/* ✅ CORRECT - Nuxt UI CSS variables */
+.component {
+  color: var(--ui-primary); /* Primary theme color */
+  background: color-mix(in srgb, var(--ui-primary) 10%, transparent);
+}
+
+/* Semantic colors */
+.success {
+  color: var(--ui-success);
+}
+.warning {
+  color: var(--ui-warning);
+}
+.error {
+  color: var(--ui-error);
+}
+.info {
+  color: var(--ui-info);
+}
+```
+
+## Nuxt UI Theme Variables (authoritative list)
+
+Use the Nuxt UI CSS variables documented here: https://ui.nuxt.com/docs/getting-started/theme/css-variables
+
+## Spacing
+
+Use rem values directly - do NOT define custom spacing variables:
+
+```css
+/* ❌ WRONG - Old custom spacing variables */
+.component {
+  padding: var(--spacing-md);
+  gap: var(--spacing-lg);
+}
+
+/* ✅ CORRECT - Direct rem values */
+.component {
+  padding: 1rem;
+  gap: 1.5rem;
+}
+```
+
+**Standard spacing scale (rem):**
+
+| Value   | Pixels | Use Case                    |
+| ------- | ------ | --------------------------- |
+| 0.25rem | 4px    | Tiny gaps, icon spacing     |
+| 0.5rem  | 8px    | Small gaps, compact padding |
+| 0.75rem | 12px   | Medium-small spacing        |
+| 1rem    | 16px   | Base padding, standard gaps |
+| 1.5rem  | 24px   | Section spacing             |
+| 2rem    | 32px   | Large section spacing       |
+| 3rem    | 48px   | Extra large spacing         |
+
+## Border Radius
+
+Use rem values directly:
+
+```css
+/* ❌ WRONG */
+.component {
+  border-radius: var(--border-radius);
+}
+
+/* ✅ CORRECT */
+.component {
+  border-radius: 0.5rem; /* 8px - standard */
+  border-radius: 0.75rem; /* 12px - cards, buttons */
+  border-radius: 50%; /* Circular elements */
+}
+```
+
+## Complete Example
+
+```css
+/* ✅ CORRECT - Using Nuxt UI variables */
+.card {
+  background: var(--ui-bg-elevated);
+  border: 1px solid var(--ui-border);
+  border-radius: 0.75rem;
+  padding: 1.5rem;
+}
+
+.card:hover {
+  border-color: var(--ui-border-accented);
+}
+
+.card-title {
+  color: var(--ui-text);
+  font-size: 1.25rem;
+  margin-bottom: 0.5rem;
+}
+
+.card-description {
+  color: var(--ui-text-muted);
+  font-size: 0.875rem;
+}
+
+.card-highlight {
+  color: var(--ui-primary);
+  background: color-mix(in srgb, var(--ui-primary) 10%, transparent);
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+}
+```
+
+## Migration from Old Variables
+
+If you encounter old variables, replace them:
+
+| Old Variable            | New Variable (Nuxt UI)       |
+| ----------------------- | ---------------------------- |
+| `--p-text-color`        | `--ui-text`                  |
+| `--p-text-muted-color`  | `--ui-text-muted`            |
+| `--p-primary-color`     | `--ui-primary`               |
+| `--p-warn-color`        | `--ui-warning`               |
+| `--p-danger-color`      | `--ui-error`                 |
+| `--surface-card`        | `--ui-bg-elevated`           |
+| `--surface-ground`      | `--ui-bg-accented`           |
+| `--surface-border`      | `--ui-border`                |
+| `--spacing-*`           | Direct rem values            |
+| `--border-radius`       | Direct rem values            |
+| `rgba(255,255,255,0.x)` | `--ui-text-muted` or similar |
+
+## Rem Conversion Reference
+
+Base font size: 16px (browser default)
+
+| rem  | px  |
+| ---- | --- |
+| 0.25 | 4   |
+| 0.5  | 8   |
+| 0.75 | 12  |
+| 1    | 16  |
+| 1.25 | 20  |
+| 1.5  | 24  |
+| 2    | 32  |
+| 3    | 48  |
+
+## Enforcement
+
+**Code Review Checklist:**
+
+- [ ] No hardcoded pixel values
+- [ ] No magic numbers without token variables
+- [ ] No arbitrary color hex codes
+- [ ] All spacing uses rem units
+- [ ] All colors use design tokens

package/templates/bootstrap/base/.agents/skills/self-improvement/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: self-improvement
+description: Shared process for agent learning artifacts and reusable handoff/plan templates.
+---
+
+# Self-Improvement Skill
+
+## Purpose
+
+Standardize how agents capture reusable learnings and how they hand off work between roles.
+
+## Required Outputs After Significant Work
+
+Each agent must update at least one of:
+
+- `docs/agents/knowledge/<agent>.md`
+- `docs/agents/handoffs/<feature-id>/*.md`
+- `docs/agents/plans/<feature-id>/plan.md`
+
+## Template Source of Truth
+
+Use templates from this skill folder:
+
+- `.agents/skills/self-improvement/templates/handoff-template.md`
+- `.agents/skills/self-improvement/templates/plan-template.md`
+
+## Working Rules
+
+1. Reuse one stable `<feature-id>` across all artifacts.
+2. Keep handoffs actionable: context, completed/open work, risks, next actions.
+3. Keep plans traceable to PRD/story requirements.
+4. Add concise dated lessons that can improve future execution.

package/templates/bootstrap/base/.agents/skills/self-improvement/templates/handoff-template.md

@@ -0,0 +1,35 @@
+# Handoff Template
+
+## Feature
+
+- ID:
+- Name:
+- From Agent:
+- To Agent:
+- Date:
+
+## Context
+
+Describe user value, constraints, and current state.
+
+## Completed
+
+-
+
+## Open Work
+
+-
+
+## Risks / Unknowns
+
+-
+
+## Required Next Actions
+
+1.
+2.
+3.
+
+## Definition of Done for Next Agent
+
+-

package/templates/bootstrap/base/.agents/skills/self-improvement/templates/plan-template.md

@@ -0,0 +1,55 @@
+# Implementation Plan Template
+
+## Metadata
+
+- Plan ID:
+- Story ID(s):
+- Author Agent: Planning Agent
+- Date:
+
+## Requirement Summary
+
+- User problem:
+- Business objective:
+- In-scope:
+- Out-of-scope:
+
+## Source Documents Reviewed
+
+- `docs/prd.md`
+- `docs/PROGRESS.md`
+- `docs/stories/...`
+
+## Proposed Solution
+
+Short architecture and flow summary.
+
+## Frontend Workstream
+
+- Tasks
+- Files likely impacted
+- Risks
+
+## Backend Workstream
+
+- API/data tasks
+- For each endpoint in scope, include unit tests covering functionality and boundary conditions
+- Schema/migration needs
+- Risks
+
+## Test Plan
+
+- Endpoint unit tests (functionality + boundary conditions)
+- Integration/E2E checks
+- Visual checks + required screenshots
+
+## Acceptance Checklist
+
+- [ ] AC1
+- [ ] AC2
+- [ ] AC3
+
+## Rollout / Recovery
+
+- Rollout notes
+- Fallback notes

package/templates/bootstrap/base/.agents/skills/visual-testing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: visual-testing
+description: Browser-driven visual verification workflow using Chrome DevTools MCP, screenshots, and lightweight image analysis.
+---
+
+# Visual Testing Skill
+
+## Primary Workflow
+
+1. Start app and authenticate test user.
+2. Navigate target flows using browser MCP tools.
+3. Capture screenshots into `test/artifacts/screenshots/`.
+4. Record visual assertions (layout, spacing, alignment, state).
+5. Compare against baseline screenshot set when available.
+
+## Screenshot Conventions
+
+- File naming: `<feature-id>_<page>_<state>.png`
+- Example: `M1.4.3_session-report_loaded.png`
+- Capture both full-page and critical component crops where useful.
+
+## Recommended Tooling
+
+- Primary: Chrome DevTools MCP screenshot + DOM snapshot
+- Optional local diff: `pixelmatch` or `looks-same` for regression checks
+- Optional AI vision review (if MCP available): use multimodal model to classify obvious layout defects
+
+## Visual QA Checklist
+
+- No clipped text at common viewport sizes
+- Primary actions visible without ambiguity
+- Spacing follows existing rhythm/tokens
+- Error and loading states are readable
+- No console errors during interaction
+
+## Output Requirements
+
+- Store screenshots in `test/artifacts/screenshots/`
+- Store QA summary in `docs/agents/handoffs/<id>/qa.md`
+- Mark each acceptance check as PASS/FAIL with evidence links

package/templates/bootstrap/base/.agents/teams/web-product/README.md

@@ -0,0 +1,65 @@
+# Web Product Multi-Agent Team
+
+This folder defines a practical multi-agent setup for this workspace.
+
+## Agents
+
+- Agent definitions are canonical in `src/agents/definitions/*.yaml`
+- `.github/agents/*.agent.md` files are generated install targets
+
+Generated install targets (VS Code):
+
+- `.github/agents/requirement-analyst.agent.md`
+- `.github/agents/planning-agent.agent.md`
+- `.github/agents/frontend-dev.agent.md`
+- `.github/agents/backend-dev.agent.md`
+- `.github/agents/code-reviewer.agent.md`
+- `.github/agents/tester.agent.md`
+- `.github/agents/documentation-writer.agent.md`
+- `.github/agents/product-team-orchestrator.agent.md`
+- `.github/agents/agent-creator.agent.md`
+
+## Shared Workflow
+
+- `workflows/feature-lifecycle.md`
+
+## Source of Truth
+
+- Agent templates: `src/agents/definitions/*.yaml`
+- Template pack metadata: `templates/bootstrap/manifest.json`
+- Bootstrap overlays: `templates/bootstrap/overlays/**`
+- Product direction: `docs/prd.md`
+- Delivery state: `docs/PROGRESS.md`
+- User stories: `docs/stories/*.md`
+- Agent plans: `docs/agents/plans/<feature-id>/plan.md`
+- Agent handoffs: `docs/agents/handoffs/<feature-id>/`
+- Agent knowledge: `docs/agents/knowledge/`
+
+## How to Use in VS Code Chat
+
+Use this sequence for each feature:
+
+1. Start with Requirement Analyst to challenge assumptions and sharpen value.
+2. Move to Planning Agent to create an implementation plan.
+3. Execute with Frontend/Backend Dev Agents in parallel where possible.
+4. Run Code Reviewer Agent for simplification, duplication, maintainability, and security checks.
+5. Validate with Tester Agent (browser flows + screenshots).
+6. If issues are found, Tester Agent hands off to Frontend/Backend Dev Agents for fixes.
+7. Feed improvements back into `docs/agents/knowledge/` and skills.
+
+## Self-Improvement Rule
+
+Every agent must produce or update at least one artifact after significant work:
+
+- A short decision or rationale note in `docs/agents/knowledge/<agent>.md`, or
+- A reusable pattern in `.agents/skills/<skill>/`.
+
+Policy source: `.agents/skills/self-improvement/SKILL.md`
+
+## Project Customization
+
+Add project-specific guidance without changing installed templates under:
+
+- `.agents/custom/skills/`
+- `.agents/custom/workflows/`
+- `.agents/custom/agents/`

package/templates/bootstrap/base/.agents/teams/web-product/workflows/feature-lifecycle.md

@@ -0,0 +1,101 @@
+# Workflow: Feature Lifecycle
+
+## Goal
+
+Drive a feature from idea to shipped quality using specialized agents and shared artifacts.
+
+## Feature ID Convention
+
+Use one stable identifier across all artifacts for a feature, for example `M1.4.3`.
+
+- Plan: `docs/agents/plans/<feature-id>/plan.md`
+- FE handoff: `docs/agents/handoffs/<feature-id>/frontend.md`
+- BE handoff: `docs/agents/handoffs/<feature-id>/backend.md`
+- Integration handoff: `docs/agents/handoffs/<feature-id>/integration.md`
+- Code review handoff: `docs/agents/handoffs/<feature-id>/code-review.md`
+- QA handoff: `docs/agents/handoffs/<feature-id>/qa.md`
+
+## Step 1 — Requirement Analysis
+
+**Agent:** Requirement Analyst  
+**Inputs:** rough idea, constraints, target user  
+**Outputs:**
+
+- Updated requirements in `docs/prd.md` (if product-level change)
+- Story-level decisions in `docs/stories/<id>.md` (if scoped feature)
+- Decision record in `docs/agents/knowledge/requirement-analyst.md`
+
+## Step 2 — Planning
+
+**Agent:** Planning Agent  
+**Inputs:** `docs/prd.md`, `docs/PROGRESS.md`, story docs  
+**Outputs:**
+
+- Implementation plan in `docs/agents/plans/<id>/plan.md`
+- Frontend task list and backend task list
+- Explicit acceptance checks
+
+## Step 3 — Implementation
+
+**Agents:** Frontend Dev + Backend Dev  
+**Inputs:** plan doc + story acceptance criteria  
+**Outputs:**
+
+- Code changes in app/server/db
+- Updated story implementation notes
+- Improvement notes in `docs/agents/knowledge/frontend-dev.md` and `docs/agents/knowledge/backend-dev.md`
+
+## Step 3.5 — Integration Handoff (Required)
+
+**Owner:** Planning Agent (or Product Team Orchestrator)  
+**Inputs:** `frontend.md` and `backend.md` handoffs in `docs/agents/handoffs/<id>/`  
+**Outputs:**
+
+- Combined readiness note in `docs/agents/handoffs/<id>/integration.md`
+- Confirmed review and test scope for Code Reviewer + Tester agents
+- Explicit unresolved dependencies list (if any)
+
+## Step 4 — Code Review
+
+**Agent:** Code Reviewer  
+**Inputs:** plan acceptance checks + integration handoff + changed files/diffs  
+**Outputs:**
+
+- Review report in `docs/agents/handoffs/<id>/code-review.md`
+- Findings grouped by simplification, duplication, maintainability, and security
+- Severity tagging (`blocker`, `major`, `minor`, `nit`) and explicit action list
+
+## Step 5 — Verification
+
+**Agent:** Tester  
+**Inputs:** plan acceptance checks + integration handoff + code review handoff + changed flows  
+**Outputs:**
+
+- Test run evidence in `docs/agents/handoffs/<id>/qa.md`
+- Screenshots in `test/artifacts/screenshots/`
+- Visual/layout notes and pass/fail decision
+
+## Step 5b — Fixes (Conditional)
+
+**Agent:** Frontend Dev / Backend Dev
+**Trigger:** Verification failure in Step 5
+**Inputs:** QA report `docs/agents/handoffs/<id>/qa.md`
+**Action:** Fix implementation bugs and handoff back to Tester or Code Reviewer.
+
+## Step 6 — Closeout
+
+**Owner:** Planning Agent (or orchestrator role)  
+**Outputs:**
+
+- Update `docs/PROGRESS.md`
+- Confirm story status in `docs/stories/<id>.md`
+- Summarize lessons in `docs/agents/knowledge/planning-agent.md`
+
+## Handoff Contract (Required)
+
+Every handoff note must include:
+
+1. Context and objective
+2. What changed / what remains
+3. Risks and assumptions
+4. Exact next action for receiving agent

package/templates/bootstrap/manifest.json

@@ -0,0 +1,32 @@
+{
+  "templateVersion": "0.1.0",
+  "schemaVersion": 1,
+  "baseRoot": "base",
+  "overlayRoot": "overlays",
+  "defaultTeam": "web-product",
+  "packs": {
+    "skills": {
+      "root": "base/.agents/skills"
+    },
+    "team": {
+      "web-product": {
+        "readme": "base/.agents/teams/web-product/README.md",
+        "workflows": "base/.agents/teams/web-product/workflows"
+      }
+    },
+    "overlays": {
+      "vscode": {
+        "id": "vscode-copilot",
+        "root": "overlays/vscode-copilot",
+        "agents": ".github/agents",
+        "mcp": ".vscode/mcp.json"
+      },
+      "claude-code": {
+        "id": "claude-code",
+        "root": "overlays/claude-code",
+        "agents": ".claude/agents",
+        "mcp": ".mcp.json"
+      }
+    }
+  }
+}

package/templates/bootstrap/overlays/claude-code/.claude/agents/agent-creator.md

@@ -0,0 +1,55 @@
+---
+name: agent-creator
+description: 🤖 Agent Creator — specialist in defining and configuring new custom subagents. Use when the team needs a new role-specific agent or when an existing agent definition needs to be updated.
+tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+# Agent Creator
+
+You are the Agent Creator for this project.
+
+## Required References
+
+- `.agents/skills/agent-creator/SKILL.md`
+- `.agents/skills/self-improvement/SKILL.md`
+
+## Objective
+
+Create and configure new custom subagents that adhere to the team's standards and best practices.
+
+## Responsibilities
+
+- Analyze requirements for new agent roles.
+- Create new agent definition files in `.claude/agents/`.
+- Use Claude Code's subagent YAML frontmatter format: `name`, `description`, `tools`, `model`, and a system prompt body.
+- Ensure new agents are properly integrated with existing skills and workflows.
+- Update team documentation to reflect the new agent structure.
+
+## Deliverables
+
+- New `md` file in `.claude/agents/`
+- Updates to `.agents/teams/web-product/README.md` listing the new agent
+- Updates to `docs/agents/README.md` if workflow changes are significant
+
+## Agent File Format
+
+```markdown
+---
+name: <agent-name>
+description: <When Claude should delegate to this agent. Include "Use proactively" if appropriate.>
+tools: Read, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+# Agent Title
+
+System prompt body...
+```
+
+## Custom Project Extensions
+
+When adapting behavior for this repository, prefer project-owned custom instructions in:
+
+- `.agents/custom/skills/`
+- `.agents/custom/workflows/`
+- `.agents/custom/agents/`

package/templates/bootstrap/overlays/claude-code/.claude/agents/backend-dev.md

@@ -0,0 +1,48 @@
+---
+name: backend-dev
+description: ⚙️ Backend Dev Agent — Nuxt/Node API and data specialist with strong contract discipline. Use when implementing backend tasks from an active plan or resolving backend QA failures.
+tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+# Backend Dev Agent
+
+You are the Backend Dev Agent for this project.
+
+## Required References
+
+- `.agents/skills/back-end-development/SKILL.md`
+- `.agents/skills/database-management/SKILL.md` when schema/migrations are involved
+- `.agents/skills/ai-integration/SKILL.md` when AI routes are involved
+- active plan in `docs/agents/plans/<id>/plan.md`
+
+## Objective
+
+Implement backend APIs/data changes with robust validation, reliability, and security.
+
+## Responsibilities
+
+- Build/modify server APIs in `server/api/`.
+- Maintain strict request/response validation.
+- Apply DB migrations and RLS updates safely.
+- Keep business logic testable and observable.
+- For each endpoint, add unit tests to cover functionality and boundaries.
+
+## Deliverables
+
+- Code/migration changes for planned backend tasks
+- Handoff note: `docs/agents/handoffs/<id>/backend.md`
+- Learning note: `docs/agents/knowledge/backend-dev.md`
+
+## Guardrails
+
+- Keep API contracts stable unless plan explicitly changes them.
+- Keep secrets server-side only.
+- Use explicit error handling and deterministic behavior.
+
+## Custom Project Extensions
+
+When adapting behavior for this repository, prefer project-owned custom instructions in:
+
+- `.agents/custom/skills/`
+- `.agents/custom/workflows/`
+- `.agents/custom/agents/`