azclaude-copilot 0.4.31 → 0.4.33

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "azclaude",
       "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 34 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
-      "version": "0.4.31",
+      "version": "0.4.33",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 34 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
   "author": {
     "name": "haytamAroui",

package/README.md

@@ -117,7 +117,7 @@ npx azclaude-copilot@latest
 ```
 
 That's it. One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
-- **First time** → full install (34 commands, 4 hooks, 15 agents, 9 skills, memory, reflexes)
+- **First time** → full install (34 commands, 4 hooks, 15 agents, 10 skills, memory, reflexes)
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
 
@@ -135,7 +135,7 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 .claude/
 ├── CLAUDE.md                 ← dispatch table: conventions, stack, routing
 ├── commands/                 ← 33 slash commands (/add, /fix, /copilot, /spec, /sentinel...)
-├── skills/                   ← 9 skills (test-first, security, architecture-advisor, frontend-design...)
+├── skills/                   ← 10 skills (test-first, security, architecture-advisor, frontend-design...)
 ├── agents/                   ← 15 agents (orchestrator, spec-reviewer, constitution-guard...)
 ├── capabilities/             ← 37 files, lazy-loaded via manifest.md (~380 tokens/task)
 ├── hooks/
@@ -807,11 +807,11 @@ Run `/level-up` at any time to see your current level and build the next one.
 
 ## Verified
 
-1462 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1473 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1462 passed, 0 failed, 1462 total
+# Results: 1473 passed, 0 failed, 1473 total
 ```
 
 ---

package/bin/cli.js

@@ -373,7 +373,7 @@ function installCommands(projectDir, cfg) {
 
 // ─── Skills (SKILL.md — model-auto-invoked) ──────────────────────────────────
 
-const SKILLS = ['session-guard', 'test-first', 'env-scanner', 'debate', 'security', 'skill-creator', 'agent-creator', 'architecture-advisor', 'frontend-design'];
+const SKILLS = ['session-guard', 'test-first', 'env-scanner', 'debate', 'security', 'skill-creator', 'agent-creator', 'architecture-advisor', 'frontend-design', 'mcp'];
 
 function installSkills(projectDir, cfg) {
   const skillsDir = path.join(projectDir, cfg, 'skills');
@@ -1194,32 +1194,44 @@ if (hasPlan && hasPendingMilestones) {
 console.log('\n════════════════════════════════════════════════');
 console.log(`  AZCLAUDE v${currentVer} — ${isFirstInstall ? 'installed' : needsUpgrade ? 'upgraded' : 'up to date'}`);
 console.log('');
+
+// First-time users get a one-liner orientation
+if (isFirstInstall) {
+  console.log('  AI coding commands for Claude Code: /setup, /add, /fix,');
+  console.log('  /copilot, /ship and 29 more. Run them inside Claude Code.');
+  console.log('');
+}
+
 console.log('  Open Claude Code in this directory, then:');
 console.log('');
 
 if (onboardingPath === 'RESUME') {
-  console.log('  You have a plan with pending work:');
+  console.log('  A plan with pending work was found:');
   console.log('');
-  console.log('    /copilot          resume autonomous build');
   console.log('    /pulse            see current state first');
+  console.log('    /copilot          resume autonomous build');
   console.log('    /analyze plan     verify plan vs reality');
+  console.log('');
+  console.log('  Starting fresh instead?');
+  console.log('');
+  console.log('    /setup            (re)configure this project');
 } else if (onboardingPath === 'EXISTING') {
   console.log('  Existing project detected:');
   console.log('');
-  console.log('    /setup            scan + configure this project');
-  console.log('    /dream            define what to build next');
-  console.log('    /blueprint        plan the next feature');
-  console.log('    /copilot .        build autonomously');
+  console.log('    /setup            scan + configure this project  ← start here');
+  console.log('    /add [feature]    start building immediately');
+  console.log('    /dream            plan a full product first');
+  console.log('    /copilot          build autonomously');
 } else {
   console.log('  New project:');
   console.log('');
-  console.log('    /setup            configure this project');
+  console.log('    /setup            configure this project  ← start here');
   console.log('    /add [feature]    start building immediately');
   console.log('    /dream            plan a full product first');
 }
 
 console.log('');
 console.log('  ─────────────────────────────────────────────');
-console.log('  docs:    github.com/haytamAroui/AZ-CLAUDE-COPILOT');
-console.log('  upgrade: npx azclaude-copilot@latest');
+console.log('  all commands: /help  ·  docs: github.com/haytamAroui/AZ-CLAUDE-COPILOT');
+console.log('  upgrade:      npx azclaude-copilot@latest');
 console.log('════════════════════════════════════════════════\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.31",
-  "description": "AI coding environment — 34 commands, 9 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.4.33",
+  "description": "AI coding environment — 34 commands, 10 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
   "bin": {
     "azclaude": "bin/cli.js",
     "azclaude-copilot": "bin/copilot.js"

package/templates/skills/mcp/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mcp
+description: >
+  MCP server recommendations and setup for Claude Code projects. Use when the user
+  asks "what MCP should I use", "add MCP", "set up MCP", "improve Claude Code",
+  "Context7", "sequential thinking", "GitHub MCP", "Playwright MCP", "Supabase MCP",
+  "Brave Search", "add web search", "add browser control", "add database access",
+  "Claude doesn't know the latest API", "wrong library version", "stale docs",
+  "hallucinating API", or when /setup detects a stack and needs to recommend
+  integrations. Also use when user wants to configure .mcp.json, add tools to
+  Claude Code, or asks which MCP works best for their stack.
+  Do NOT trigger when: user is asking about AZCLAUDE's own security scanner for
+  MCP configs (use security skill). Do NOT trigger for generic npm package questions.
+---
+
+# MCP Integration
+
+MCP servers extend Claude Code with live capabilities: real-time docs, web search,
+browser control, database access. AZCLAUDE recommends MCPs based on your stack —
+it never bundles them (zero-dep rule).
+
+## Step 0: Detect Stack
+
+Read these before recommending:
+```bash
+cat package.json 2>/dev/null | grep -E '"next"|"react"|"supabase"|"prisma"|"postgres"|"playwright"' | head -10
+cat CLAUDE.md 2>/dev/null | grep -E "Stack:|Domain:" | head -5
+ls .mcp.json ~/.claude/claude_desktop_config.json 2>/dev/null && echo "mcp=configured" || echo "mcp=none"
+```
+
+## Step 1: Universal — Recommend for Every Project
+
+These improve ALL AZCLAUDE workflows regardless of stack:
+
+| MCP | What it fixes | Install |
+|-----|--------------|---------|
+| **Context7** | `/copilot` and `/add` write code against stale training data — wrong API signatures, deprecated methods. Context7 injects current docs at prompt time. | `claude mcp add context7 npx @upstash/context7-mcp` |
+| **Sequential Thinking** | Orchestrator, milestone-builder, and `/blueprint` make better multi-step decisions when they can reason iteratively with branching. | `claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking` |
+
+Always recommend both. They cost nothing (free, no API key) and improve every session.
+
+## Step 2: Stack-Specific — Recommend Based on Detection
+
+| If stack contains | Recommend | Why |
+|------------------|-----------|-----|
+| Any GitHub repo | **GitHub MCP** | Richer than `gh` CLI for `/issues`, `/ship`, PR reviews, repo search |
+| Any web project | **Playwright MCP** | E2E testing — pairs with qa-engineer agent and `/test` |
+| `supabase` in deps | **Supabase MCP** | Schema introspection, migrations, Edge Functions from within Claude Code |
+| `postgres`/`prisma` in deps | **PostgreSQL MCP** | Natural language queries, schema exploration during development |
+| Debugging / `/fix` heavy | **Brave Search** | Real-time error lookup, CVE research for `/sentinel`, library issue tracking |
+| Design-to-code workflow | **Figma MCP** | Translate Figma components directly to code |
+
+## Step 3: Install Commands
+
+```bash
+# Universal — install these for every project
+claude mcp add context7 npx @upstash/context7-mcp
+claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
+
+# GitHub (no API key needed with Claude Code auth)
+claude mcp add github npx @modelcontextprotocol/server-github
+
+# Playwright (Microsoft official)
+claude mcp add playwright npx @playwright/mcp@latest
+
+# Brave Search (requires BRAVE_API_KEY)
+claude mcp add brave-search npx @modelcontextprotocol/server-brave-search \
+  --env BRAVE_API_KEY=${BRAVE_API_KEY}
+
+# Supabase (requires SUPABASE_ACCESS_TOKEN)
+claude mcp add supabase npx @supabase/mcp-server-supabase \
+  --env SUPABASE_ACCESS_TOKEN=${SUPABASE_ACCESS_TOKEN}
+
+# PostgreSQL
+claude mcp add postgres npx @modelcontextprotocol/server-postgres \
+  postgresql://localhost/mydb
+```
+
+## Step 4: Security Rules (Always Apply)
+
+Before writing any `.mcp.json`:
+- **Never hardcode secrets** — use `${ENV_VAR}` syntax always
+- **Pin versions** — use `@1.2.3` not `@latest` in production
+- **Scope to project** — use `claude mcp add --scope project` not global when possible
+- Run `/sentinel` after adding MCPs to verify the config scores cleanly
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@1.0.0"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
+    }
+  }
+}
+```
+
+## Step 5: Verify Installation
+
+```bash
+claude mcp list                    # shows configured servers
+claude mcp get context7            # shows context7 config
+```
+
+Then test in Claude Code: ask Claude "use context7 to get the latest React docs" — if it returns live docs, it's working.
+
+For full MCP catalog: `references/mcp-catalog.md`

package/templates/skills/mcp/references/mcp-catalog.md

@@ -0,0 +1,54 @@
+# MCP Catalog — Full Reference
+
+## Universal (all projects)
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Context7 | `@upstash/context7-mcp` | None | Inject live library docs into /add, /fix, /copilot |
+| Sequential Thinking | `@modelcontextprotocol/server-sequential-thinking` | None | Better reasoning in orchestrator, /blueprint, /debate |
+
+## Developer Tools
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| GitHub | `@modelcontextprotocol/server-github` | `GITHUB_TOKEN` (optional) | /issues, /ship, PR creation, repo search |
+| Playwright | `@playwright/mcp` | None | E2E tests with qa-engineer, /test |
+| Brave Search | `@modelcontextprotocol/server-brave-search` | `BRAVE_API_KEY` | /fix error lookup, /sentinel CVE research |
+| Firecrawl | `firecrawl-mcp` | `FIRECRAWL_API_KEY` | Scrape live docs, competitor analysis |
+| Sentry | `@sentry/mcp-server` | `SENTRY_TOKEN` | Pipe production errors into /fix sessions |
+
+## Database
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Supabase | `@supabase/mcp-server-supabase` | `SUPABASE_ACCESS_TOKEN` | Schema exploration, migrations, Edge Functions |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` | DB URL | Natural language queries during dev |
+| SQLite | `@modelcontextprotocol/server-sqlite` | None | Local DB for prototypes |
+
+## Design & Content
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Figma | figma-mcp | `FIGMA_TOKEN` | Design-to-code with frontend-design skill |
+
+---
+
+## Install All Universal MCPs
+
+```bash
+claude mcp add context7 npx @upstash/context7-mcp
+claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
+```
+
+## Verify
+
+```bash
+claude mcp list
+```
+
+## Security Checklist
+
+- [ ] No plaintext secrets in `.mcp.json` — use `${ENV_VAR}`
+- [ ] Versions pinned (not `@latest`) for production
+- [ ] Run `/sentinel` after changes to score MCP config
+- [ ] `.mcp.json` in `.gitignore` if it contains env refs to local paths

package/templates/skills/security/references/security-details.md

@@ -15,7 +15,7 @@ Claude plans & calls tools
 [pre-tool-use.js] — intercepts 3 tool types before execution:
   Bash  → blocks curl|bash RCE, destructive rm; warns npm install, env var echo
   Read  → warns on credential file access (.env, secrets.json, id_rsa, .pem)
-  Write → 14 code vulnerability pattern rules (see table below)
+  Write → 19 code vulnerability pattern rules (see table below)
        ↓                          ↓
 [post-tool-use.js]         /tmp/.azclaude-seclog-{PID}
   behavioral sequence             ↑ shared session event log
@@ -106,6 +106,10 @@ Scans all Edit/Write/MultiEdit operations. Warnings → stderr. Secrets → exit
 - `yaml-unsafe-load` → use `yaml.safe_load()` — always
 - `path-traversal` → use `path.resolve()` + validate result starts with allowed base dir
 - `prompt-injection-write` → review content before writing to files that will be read by AI agents; never embed instruction-like text in project files
+- `c-gets` → use `fgets(buf, sizeof(buf), stdin)` or `getline()` — always specify buffer bounds
+- `php-shell-exec` → use `escapeshellarg()` / `escapeshellcmd()`, or avoid shell calls entirely
+- `java-runtime-exec` → use `new ProcessBuilder(List.of("cmd", "arg1")).start()` with a String array
+- `jinja2-ssti` → use `render_template("file.html", ...)` with a file-based template, never render raw strings
 - `hardcoded-secret` → use environment variables (`process.env.MY_SECRET` / `os.environ['MY_SECRET']`)
 
 ---