code-ai-installer 1.3.0 → 1.4.0

package/locales/en/.agents/skills/board/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: board
+description: Project Board Management — creation of tasks with IDs, statuses ☐/⏳/☑/⚠️, updates after each step, visible checklist in every Conductor's message.
+---
+
+# Skill: Board & Task Management
+
+How the Conductor (Main Agent) manages the task board and tracks progress.
+
+**Sections:**
+1. [Core Principles](#1-principles)
+2. [Task Statuses](#2-statuses)
+3. [Board Structure](#3-structure)
+4. [Updating the Board](#4-updating)
+5. [Conductor's Message Format](#5-message-format)
+6. [Anti-patterns](#6-anti-patterns)
+
+---
+
+## 1. Core Principles
+
+- **Visibility:** The board MUST be visible in every message from the Conductor.
+- **Traceability:** Every task has a unique ID (e.g., `T-01`, `BUG-42`).
+- **Granularity:** Tasks should be small enough to complete in 1-2 agent interactions.
+- **Single Source of Truth:** If it's not on the board, it doesn't exist.
+- **Handoff Linking:** When handing off to an agent, reference the Task ID.
+
+---
+
+## 2. Task Statuses
+
+Use exactly these symbols for quick visual parsing:
+
+| Symbol | Status | Meaning |
+|:---:|---|---|
+| `☐` | **TODO** | Task identified, not started yet. |
+| `⏳` | **IN PROGRESS** | Agent is currently working on it. |
+| `☑` | **DONE** | Validated and completed (DoD met). |
+| `⚠️` | **BLOCKED** | Needs user input, clarification, or depends on another blocked task. |
+| `❌` | **CANCELED** | Won't do, out of scope, or obsolete. |
+
+---
+
+## 3. Board Structure
+
+The board is a markdown checklist grouped by Epic or Phase.
+
+### Typical Layout
+
+```markdown
+## 📋 Project Board
+
+### Phase 1: Planning & Design (Gate 1 & 2)
+- ☑ [T-01] Gather Requirements (PM)
+- ☑ [T-02] Draft PRD (PM)
+- ⏳ [T-03] Create UX Spec (UX Designer) - *Waiting for review*
+- ☐ [T-04] Architecture Document (Architect)
+- ☐ [T-05] API Contracts (Architect)
+
+### Phase 2: Implementation (Gate 3)
+- ☐ [T-06] DB Schema Setup (Senior Full Stack)
+- ☐ [T-07] Build Login Flow (Senior Full Stack)
+...
+```
+
+---
+
+## 4. Updating the Board
+
+### When to update
+
+1. **New Request:** Parse user request into `T-xx` items. Add them as `☐`.
+2. **Before Handoff:** Change target task to `⏳`.
+3. **After Handoff (Success):** Change task to `☑`.
+4. **After Handoff (Failure/Bug):** Change to `⚠️` or spawn a new `[BUG-xx]` item.
+5. **Phase Complete:** Collapse completed phases or summarize them if the board gets too long.
+
+### Spawning subtasks
+
+If a task `T-06 (Build Login Flow)` turns out to be complex, break it down:
+
+```markdown
+- ⏳ [T-06] Build Login Flow
+  - ☑ [T-06.1] Setup JWT middleware
+  - ⏳ [T-06.2] Create `/login` endpoint
+  - ☐ [T-06.3] Frontend Login form
+```
+
+---
+
+## 5. Conductor's Message Format
+
+Every response from the Conductor to the User MUST follow this structure:
+
+```markdown
+# 🎭 Conductor
+
+**Status Update:** <1-2 sentences summarizing what just happened>
+
+<Answer to user / Recommendations / Next Steps>
+
+---
+## 📋 Current Board
+- ☑ [T-01] Initial setup
+- ⏳ [T-02] Implementing Feature X (Full Stack doing this now)
+- ☐ [T-03] Testing
+- ⚠️ [T-04] Clarify API rate limits (need User input)
+
+**Next action:** Handoff T-02 to Senior Full Stack. Do you approve?
+```
+
+---
+
+## 6. Anti-patterns
+
+| ❌ Anti-pattern | ✅ Solution |
+|----------------|-----------|
+| **Forgetting the board** | Conductor replies with just text. The user loses context. ALWAYS include the board. |
+| **Tasks without IDs** | "Fix login bug". Hard to reference. Use `[BUG-01] Fix login bug`. |
+| **Vague statuses** | Using "Pending" or mixed symbols. Stick to `☐, ⏳, ☑, ⚠️, ❌`. |
+| **Silent updates** | Changing a task from `⏳` to `☑` without explaining *how* it was validated. |
+| **Mega-tasks** | `☐ [T-01] Build the entire app`. Break it down. |
+
+---
+
+## See also
+- `$handoff` — How to pass a task to another agent.
+- `$gates` — How phases map to pipeline gates.
+- `$pm_backlog` — How the PM originally creates the list of tasks.

package/locales/en/.agents/skills/board/agents/claude.json

@@ -0,0 +1,16 @@
+{
+  "name": "board",
+  "display_name": "Project Board",
+  "description": "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message.",
+  "default_prompt": "Use $board when the task matches the \"Project Board\" skill.",
+  "triggers": [
+    "board",
+    "Project Board",
+    "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message"
+  ],
+  "capabilities": [
+    "board"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/board/agents/copilot.json

@@ -0,0 +1,16 @@
+{
+  "name": "board",
+  "display_name": "Project Board",
+  "description": "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message.",
+  "default_prompt": "Use $board when the task matches the \"Project Board\" skill.",
+  "triggers": [
+    "board",
+    "Project Board",
+    "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message"
+  ],
+  "capabilities": [
+    "board"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/board/agents/gemini.json

@@ -0,0 +1,16 @@
+{
+  "name": "board",
+  "display_name": "Project Board",
+  "description": "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message.",
+  "default_prompt": "Use $board when the task matches the \"Project Board\" skill.",
+  "triggers": [
+    "board",
+    "Project Board",
+    "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message"
+  ],
+  "capabilities": [
+    "board"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/board/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Project Board"
+  short_description: "Manage the Project Board - create task IDs, maintain statuses, update progress after each step,…"
+  default_prompt: "Use $board when the task matches the \"Project Board\" skill."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/locales/en/.agents/skills/board/agents/qwen.json

@@ -0,0 +1,16 @@
+{
+  "name": "board",
+  "display_name": "Project Board",
+  "description": "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message.",
+  "default_prompt": "Use $board when the task matches the \"Project Board\" skill.",
+  "triggers": [
+    "board",
+    "Project Board",
+    "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message"
+  ],
+  "capabilities": [
+    "board"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/board/agents/skill.yaml

@@ -0,0 +1,20 @@
+version: 1
+name: "board"
+display_name: "Project Board"
+description: "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message."
+default_prompt: "Use $board when the task matches the \"Project Board\" skill."
+triggers:
+  - "board"
+  - "Project Board"
+  - "Manage the Project Board - create task IDs, maintain statuses, update progress after each step, and keep a visible checklist in every conductor message"
+capabilities:
+  - "board"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"

package/locales/en/.agents/skills/cloud_infrastructure_security/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: cloud_infrastructure_security
+description: Cloud/Infra/CI/CD Security Review — IAM, secrets manager, network, logging/monitoring, supply chain, CDN/WAF, backup/DR.
+---
+
+# Skill: Cloud Infrastructure Security Review
+
+Security review for cloud environments, infrastructure as code, and CI/CD pipelines.
+
+**Sections:**
+1. [Workflow](#1-workflow)
+2. [Checklist (Cloud Security Baseline)](#2-checklist)
+3. [Verification Methods](#3-methods)
+4. [Red Flags](#4-red-flags)
+5. [Output Template](#5-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Get the architecture context (from $architecture_doc & $deployment_ci_plan)
+   └── Hosting platform, CI/CD tools, external services
+
+2. For each cloud security domain:
+   a. IAM & Authentication
+   b. Secrets Management
+   c. Network Security & Boundaries
+   d. Logging & Monitoring
+   e. Compute & Container Security
+   f. CI/CD Supply Chain Security
+
+3. Review configuration files (IaC, manifests, workflow files)
+   └── Search for hardcoded secrets, misconfigurations
+
+4. Formulate the Security Gap Report (Output Template)
+```
+
+---
+
+## 2. Checklist (Cloud Security Baseline)
+
+### 2.1 IAM & Authentication
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-01 | Principle of Least Privilege (PoLP) enforced for all roles | 🔴 P0 | ☐ |
+| CLOUD-02 | No shared accounts/credentials used | 🔴 P0 | ☐ |
+| CLOUD-03 | MFA enforced for all console access | 🔴 P0 | ☐ |
+| CLOUD-04 | Service Accounts instead of user credentials for automation | 🔴 P0 | ☐ |
+
+### 2.2 Secrets Management
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-05 | Secrets stored in a dedicated Secret Manager (Vault, AWS Secrets, GitHub Secrets) | 🔴 P0 | ☐ |
+| CLOUD-06 | NO hardcoded credentials in source code or `Dockerfile` | 🔴 P0 | ☐ |
+| CLOUD-07 | Environment variables not exposing secrets (e.g., in React frontend code) | 🔴 P0 | ☐ |
+| CLOUD-08 | Audit trail for secret access enabled | 🟠 P1 | ☐ |
+
+### 2.3 Network Security & Boundaries
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-09 | Default deny inbound traffic rules | 🔴 P0 | ☐ |
+| CLOUD-10 | Databases NOT exposed to the public internet | 🔴 P0 | ☐ |
+| CLOUD-11 | WAF / DDoS protection active for public endpoints | 🟠 P1 | ☐ |
+| CLOUD-12 | TLS 1.2+ enforced for all in-transit data (HTTPS) | 🔴 P0 | ☐ |
+| CLOUD-13 | Private network/VPC/Subnets used to isolate layers | 🟠 P1 | ☐ |
+
+### 2.4 Logging & Monitoring
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-14 | Centralized logging for all infrastructure components | 🟠 P1 | ☐ |
+| CLOUD-15 | Access logs enabled on storage buckets / databases | 🟡 P2 | ☐ |
+| CLOUD-16 | Alerts configured for critical security events (failed logins, root access) | 🟠 P1 | ☐ |
+
+### 2.5 Compute & Container Security
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-17 | Containers do NOT run as `root` user | 🔴 P0 | ☐ |
+| CLOUD-18 | Minimal base images used (e.g., `alpine`, `distroless`) | 🟠 P1 | ☐ |
+| CLOUD-19 | Read-only root filesystem where possible | 🟡 P2 | ☐ |
+
+### 2.6 CI/CD & Supply Chain
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| CLOUD-20 | Dependency scanning (SCA) active in CI | 🔴 P0 | ☐ |
+| CLOUD-21 | SAST (Static Analysis) tools running on PRs | 🟠 P1 | ☐ |
+| CLOUD-22 | Secrets scanning active (preventing commits with secrets) | 🔴 P0 | ☐ |
+| CLOUD-23 | Branch protection rules: Require PR reviews, disallow direct commits to `main` | 🔴 P0 | ☐ |
+
+---
+
+## 3. Verification Methods
+
+### Grep patterns for misconfigurations
+
+```bash
+# 🔴 P0: Detect Hardcoded Secrets (General patterns)
+grep_search: Query="password\s*=\s*[\"'][^\"']+[\"']" IsRegex=true
+grep_search: Query="secret\s*=\s*[\"'][^\"']+[\"']" IsRegex=true
+grep_search: Query="token\s*=\s*[\"'][a-zA-Z0-9_\-]+[\"']" IsRegex=true
+grep_search: Query="api[_-]?key\s*=\s*[\"'][a-zA-Z0-9_\-]+[\"']" IsRegex=true
+
+# 🔴 P0: Dockerfile running as root
+grep_search: Query="USER root" Includes=["Dockerfile*"]
+# Verify if there is a 'USER node' (or similar non-root) at the end of Dockerfile
+
+# 🔴 P0: Exposed database ports in Docker Compose
+grep_search: Query="\"27017:27017\"" Includes=["docker-compose.yml"]
+grep_search: Query="\"5432:5432\"" Includes=["docker-compose.yml"]
+
+# 🟠 P1: Missing SCA/vuln checks in GitHub Actions
+grep_search: Query="npm audit" Includes=[".github/workflows/*"]
+grep_search: Query="dependabot" Includes=[".github/workflows/*"]
+```
+
+---
+
+## 4. Red Flags
+
+| Red Flag | Description | Severity | Fix |
+|----------|-------------|----------|-----|
+| **Public Database** | DB port (e.g., 5432, 27017) bound to `0.0.0.0` or open in Security Group | 🔴 P0 | Bind to localhost (`127.0.0.1`) or inside private VPC. |
+| **Secrets in code** | AWS keys, API tokens committed to repository | 🔴 P0 | Revoke immediately. Use `.env` file + secret manager. |
+| **Full Admin IAM** | Workloads or user roles have `AdministratorAccess` wildcard (`*`) | 🔴 P0 | Scope down to specific actions and resources (PoLP). |
+| **Root Containers** | Docker images running as default `root` | 🔴 P0 | Add `USER node` (or equivalent) in Dockerfile. |
+| **No Branch Protection** | Main branch accepts direct commits without review | 🔴 P0 | Enforce PRs and 1+ reviewers in GitHub settings. |
+
+---
+
+## 5. Output Template
+
+```markdown
+# Cloud Infrastructure Security Review
+
+**Scope:** <Infrastructure repo / CI/CD pipeline / Module>
+**Reviewer:** Reviewer Agent
+**Date:** YYYY-MM-DD
+**Reference:** $deployment_ci_plan, $docker_kubernetes_architecture
+
+## Findings Summary
+
+- **Total Checks Assessed:** X
+- **P0 Blockers:** Y
+- **P1 Concerns:** Z
+- **P2 Recommendations:** W
+
+## Detailed Findings
+
+| # | Severity | Check Code | File/Component | Finding Description | Fix Recommended |
+|---|----------|------------|----------------|---------------------|-----------------|
+| 1 | 🔴 P0 | CLOUD-06 | `docker-compose.yml` | DB password hardcoded (`MYSQL_PASSWORD=root`) | Inject via `.env` file and Docker Secrets. |
+| 2 | 🔴 P0 | CLOUD-17 | `Dockerfile` | Image runs as root | Add `USER node` before `CMD`. |
+| 3 | 🟠 P1 | CLOUD-21 | `.github/workflows/ci.yml` | No SAST/SCA step in pipeline | Add `npm audit` or CodeQL step to CI. |
+| 4 | 🟡 P2 | CLOUD-19 | `deployment.yaml` | Root FS is writable | Mount specific paths as writeable, set `readOnlyRootFilesystem: true`. |
+
+## Compliance Overview (by Domain)
+
+| Domain | Status |
+|--------|:------:|
+| IAM & Auth | ✅ |
+| Secrets Management | ❌ |
+| Network Security | ✅ |
+| Logging & Monitoring | ⚠️ |
+| Compute/Containers | ❌ |
+| CI/CD & Supply Chain | ⚠️ |
+
+## Verdict
+- [ ] **PASS** - Cloud baseline met. Safe to deploy.
+- [ ] **WARN** - Minor deviations (P1/P2). Fix before next release.
+- [x] **FAIL** - Critical P0 issues found. Do NOT deploy until fixed.
+```
+
+---
+
+## See also
+- `$deployment_ci_plan` — The plan this review acts upon.
+- `$docker_kubernetes_architecture` — Best practices for containerization.
+- `$dependency_supply_chain_review` — Deeper dive into SCA and dependencies.
+- `$security_review_baseline` — AppSec layer (complementary to this Cloud/Infra layer).

package/locales/en/.agents/skills/code_review_checklist/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: code_review_checklist
+description: Universal review checklist — code quality, readability, testability, security, contracts, Definition of Done.
+---
+
+# Skill: Universal Code Review Checklist
+
+Checklist for the Reviewer Agent or self-review before handoff.
+
+**Sections:**
+1. [When to use](#1-when-to-use)
+2. [Checklist](#2-checklist)
+3. [Reviewer's Output Format](#3-reviewer-output)
+4. [Anti-patterns](#4-anti-patterns)
+
+---
+
+## 1. When to use
+
+Use this checklist *after* the Senior Full Stack developer has finished coding, but *before* passing the task to QA (Tester) or closing it.
+
+The Reviewer Agent uses this checklist as the primary framework.
+
+---
+
+## 2. Checklist
+
+### 2.1 Definition of Done (DoD)
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-01 | PRD requirements are met (no missing scope) | 🔴 P0 | ☐ |
+| REV-02 | Code runs without crashing (no obvious syntax errors) | 🔴 P0 | ☐ |
+| REV-03 | UX Spec visually matched (no missing UI elements) | 🔴 P0 | ☐ |
+| REV-04 | No `console.log` or debug code left behind | 🟠 P1 | ☐ |
+
+### 2.2 Architecture & Contracts
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-05 | Code follows `$architecture_doc` layers | 🔴 P0 | ☐ |
+| REV-06 | API implementation matches `$api_contracts` exactly | 🔴 P0 | ☐ |
+| REV-07 | New data model (if any) is documented | 🟠 P1 | ☐ |
+| REV-08 | ADR created if a significant architectural choice was made | 🟠 P1 | ☐ |
+
+### 2.3 Code Quality & Best Practices
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-09 | ESLint / Type checking passes (no red squiggles) | 🔴 P0 | ☐ |
+| REV-10 | Meaningful variable/function naming (no `data1`, `temp`) | 🟠 P1 | ☐ |
+| REV-11 | JSDoc present for all functions | 🔴 P0 | ☐ |
+| REV-12 | Functions are short and focused (< 40 lines ideally) | 🟠 P1 | ☐ |
+| REV-13 | No magic numbers or hardcoded strings | 🟠 P1 | ☐ |
+| REV-14 | React: No useless re-renders, correct memoization | 🟠 P1 | ☐ |
+| REV-15 | Go: correct error handling (`if err != nil`), no hidden panics | 🔴 P0 | ☐ |
+
+### 2.4 Error Handling & Logging
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-16 | Errors are caught (try/catch or `.catch()`) and handled | 🔴 P0 | ☐ |
+| REV-17 | Error format follows contract (`{ error: { code, message } }`) | 🔴 P0 | ☐ |
+| REV-18 | Structured logging used for significant events (not just `console.error`) | 🟠 P1 | ☐ |
+
+### 2.5 Security Basics
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-19 | Inputs are validated against boundary schemas (e.g., Zod) | 🔴 P0 | ☐ |
+| REV-20 | Protected routes check Auth properly | 🔴 P0 | ☐ |
+| REV-21 | No secrets (API keys, passwords) in code or frontend bundle | 🔴 P0 | ☐ |
+| REV-22 | Safe HTML rendering (dangerouslySetInnerHTML only if sanitized) | 🔴 P0 | ☐ |
+
+### 2.6 Testing
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| REV-23 | Unit tests written or updated for new logic | 🔴 P0 | ☐ |
+| REV-24 | Tests pass successfully | 🔴 P0 | ☐ |
+| REV-25 | Edge cases and error paths tested | 🟠 P1 | ☐ |
+
+---
+
+## 3. Reviewer's Output Format
+
+If passing the review:
+
+```markdown
+# Code Review: Approved
+
+All checks passed.
+- **DoD:** Met
+- **Code Quality:** Good, proper TDD cycle used.
+- **Contracts:** API matches spec perfectly.
+
+**Next Action:** Handoff to Tester Agent.
+```
+
+If requesting changes:
+
+```markdown
+# Code Review: Changes Requested
+
+## P0 Blockers (Must Fix)
+- **REV-11 (JSDoc):** `calculateTotal()` in `src/utils/cart.js:45` is missing JSDoc.
+- **REV-19 (Security):** `POST /checkout` is missing Zod body validation.
+
+## P1 Recommendations (Should Fix)
+- **REV-13 (Code Quality):** Hardcoded tax rate `0.2` in `cart.js:52`. Extract to constant.
+- **REV-14 (React):** Define `fetchData` outside `useEffect` or wrap in `useCallback` in `Cart.tsx:20`.
+
+**Next Action:** Return to Senior Full Stack to fix P0/P1 issues.
+```
+
+---
+
+## 4. Anti-patterns
+
+| ❌ Anti-pattern | ✅ Solution |
+|----------------|-----------|
+| **Rubber stamping** | Actually run `npm run test` or check the code logic. Don't just say "LGTM". |
+| **Nitpicking without P0/P1 labels** | Clearly separate blockers (P0) from stylistic suggestions (P2). |
+| **Ignoring the contract** | The code might be beautiful but if it returns HTTP 200 instead of 201 as per `$api_contracts`, it's a bug. |
+| **Skipping security checks** | Always check for input validation and auth boundaries. |
+
+---
+
+## See also
+- `$api_contract_compliance_review` — Deeper dive into API contracts.
+- `$architecture_compliance_review` — Deeper dive into layer boundaries.
+- `$security_review` — Deeper dive into AppSec.
+- `$tests_quality_review` — Deeper dive into test quality.

package/locales/en/.agents/skills/current_state_analysis/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: current_state_analysis
+description: Analysis of the current repository architecture — conventions, patterns, tech debt, scaling bottlenecks, security risks, and consistency.
+---
+
+# Skill: Current State Analysis
+
+How to audit a repository before making major architectural decisions or refactoring.
+
+**Sections:**
+1. [When to use](#1-when-to-use)
+2. [Workflow](#2-workflow)
+3. [Analysis Areas](#3-analysis-areas)
+4. [Output Template](#4-output)
+
+---
+
+## 1. When to use
+
+The Architect or Senior Full Stack agent uses this skill:
+- **During Discovery:** When taking over an existing repository.
+- **Before major refactoring:** To understand the baseline.
+- **Before system design:** To identify constraints and existing patterns that shouldn't be duplicated.
+
+---
+
+## 2. Workflow
+
+```
+1. Get the repository structure (find_by_name, ls)
+2. Identify the technology stack (package.json, go.mod, dockerfile)
+3. For each analysis area (Architecture, Data, UI, DX):
+   a. Sample 3-5 representative files
+   b. Look for consistency (e.g., are there 3 ways to fetch data?)
+   c. Identify red flags (hardcoded secrets, missing auth, god objects)
+4. Synthesize the findings into the Analysis Report
+5. Propose immediate remediation steps (if requested)
+```
+
+---
+
+## 3. Analysis Areas
+
+### 3.1 Architecture & Structure
+
+Check how the code is organized.
+
+| What to look for | Tooling / Pattern | Good | Bad |
+|------------------|-------------------|------|-----|
+| **Module boundaries** | `find_by_name`, structure | By feature (`features/products`) or layer (`src/controllers`) | Flat `src/` with 50 files, or `misc/` folder |
+| **Data flow** | `grep "fetch("` or `grep "axios"` | Through explicit services/API clients | Directly from UI components |
+| **State management** | `package.json`, React Context | Zustand, RTK Query, or well-scoped Context | Prop drilling 5 levels deep, redundant global state |
+| **Routing** | React Router / Next.js app dir | Centralized, lazy loaded where needed | Scattered `<Route>` definitions, no 404 handling |
+
+### 3.2 Code Quality & Consistency
+
+Check if the team is writing code the same way.
+
+| What to look for | Tooling / Pattern | Good | Bad |
+|------------------|-------------------|------|-----|
+| **Linting/Formatting**| `package.json` (ESLint, Biome, Prettier) | Strict CI checks, `biome.json` | Missing, or lots of `eslint-disable` |
+| **Naming Conventions**| Sampling files | `camelCase` for vars, `PascalCase` for React | Mixed `snake_case` and `camelCase` in JS |
+| **Component Size** | File sizes | < 200 lines, focused | 1000+ line God Components |
+| **Testing** | `__tests__` or `*.test.ts` | High coverage on business logic | No tests, or only empty generated tests |
+
+### 3.3 Security & Resiliency
+
+Check for obvious vulnerabilities and fragility.
+
+| What to look for | Tooling / Pattern | Good | Bad |
+|------------------|-------------------|------|-----|
+| **Secrets** | `grep "API_KEY"` or `grep "password"` | Environment variables (`process.env`) | Hardcoded tokens in source code |
+| **Authentication** | Middleware/HOCs | Centralized auth check / protected routes | Ad-hoc checks, leaked sensitive data |
+| **Error Handling** | `try/catch`, Error Boundaries | Global error boundary, unified API error format | Unhandled promise rejections, blank screens |
+| **Dependencies** | `npm audit`, `package.json` | Up-to-date, minimal external deps | Known vulnerabilities, 5 different date libraries |
+
+### 3.4 UI & Performance
+
+Check how the frontend is built and how it performs.
+
+| What to look for | Tooling / Pattern | Good | Bad |
+|------------------|-------------------|------|-----|
+| **Styling Strategy** | CSS Modules, Tailwind, WDS | Consistent use of one strategy | Mixed inline styles, global CSS, and Tailwind |
+| **Rendering** | Over-fetching, hydration | Memoization where needed, optimized images | 10MB bundle, `useEffect` infinite loops |
+| **Accessibility (a11y)**| `aria-`, semantic HTML | `<button>`, native focus, correct contrast | `onClick` on `<div>` without keyboard support |
+
+---
+
+## 4. Output Template
+
+```markdown
+# Current State Analysis: <Project/Module Name>
+
+**Date:** YYYY-MM-DD
+**Analyst:** <Agent Role>
+
+## 1. Executive Summary
+<2-3 sentences summarizing the overall health and major findings.>
+
+## 2. Tech Stack & Architecture
+- **Frontend:** React 18, Vite, Zustand
+- **Backend:** Node.js, Express (if monolithic repo)
+- **Styling:** CSS Modules
+- **Pattern:** Layered architecture (Controllers -> Services)
+
+## 3. Findings
+
+### 3.1 Architecture & Consistency
+- ✅ **Good:** Routing is centralized in `src/routes.tsx`.
+- ⚠️ **Warning:** Two different data fetching patterns found (raw `fetch` vs custom `apiClient`). Need to unify.
+- 🔴 **Red Flag:** `Dashboard.jsx` is 850 lines long and handles rendering, data fetching, and complex logic (God Object).
+
+### 3.2 Security & Error Handling
+- ✅ **Good:** Passwords are never sent to the client.
+- 🔴 **Red Flag:** Production API keys found hardcoded in `src/config/keys.js`. (Requires immediate rotation and .env extraction).
+- ⚠️ **Warning:** Missing global React Error Boundary. Unhandled exceptions crash the whole tree.
+
+### 3.3 UI & Code Quality
+- ✅ **Good:** ESLint is configured and running strictly.
+- ⚠️ **Warning:** Minimal unit test coverage (only 3 tests exist).
+
+## 4. Recommendations & Tech Debt
+
+**Immediate Remediation (P0):**
+1. Extract secrets from `src/config/keys.js` to `.env`.
+2. Refactor `Dashboard.jsx` into smaller pure components.
+
+**Short-term Tech Debt (P1):**
+1. Unify data fetching to use `apiClient` exclusively.
+2. Implement global Error Boundary.
+
+**Long-term Strategy (P2):**
+1. Introduce Vitest for unit testing critical services.
+```
+
+---
+
+## See also
+- `$architecture_doc` — Use the analysis to propose the new architecture.
+- `$system_design_checklist` — To ensure no areas are missed during redesign.
+- `$security_review_baseline` — For deeper security audits.