azclaude-copilot 0.4.21 → 0.4.23

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "azclaude",
-      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 33 commands, 8 auto-invoked skills, 13 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 — 102-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.19",
+      "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 — 102-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.23",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.4.19",
-  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 33 commands, 8 auto-invoked skills, 13 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 — 102-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.23",
+  "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 — 102-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",
     "url": "https://github.com/haytamAroui"

package/README.md

@@ -61,7 +61,7 @@ AZCLAUDE inverts this. **You start with almost nothing. The environment builds i
 npx azclaude-copilot@latest   # one command. that's it.
 ```
 
-No agent files to write. No skills to configure. No prompt engineering. `npx azclaude-copilot` installs 33 commands, 4 hooks, memory structure, and a manifest. The rest is generated from your actual codebase as you work. Run the same command again later — it auto-detects whether to skip, install, or upgrade.
+No agent files to write. No skills to configure. No prompt engineering. `npx azclaude-copilot` installs 34 commands, 4 hooks, memory structure, and a manifest. The rest is generated from your actual codebase as you work. Run the same command again later — it auto-detects whether to skip, install, or upgrade.
 
 **What the environment looks like across sessions:**
 
@@ -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 (33 commands, 4 hooks, 13 agents, 8 skills, memory, reflexes)
+- **First time** → full install (34 commands, 4 hooks, 15 agents, 9 skills, memory, reflexes)
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
 
@@ -129,14 +129,14 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ## What You Get
 
-**33 commands** · **8 auto-invoked skills** · **13 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
+**34 commands** · **9 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
 
 ```
 .claude/
 ├── CLAUDE.md                 ← dispatch table: conventions, stack, routing
 ├── commands/                 ← 33 slash commands (/add, /fix, /copilot, /spec, /sentinel...)
-├── skills/                   ← 8 skills (test-first, security, architecture-advisor...)
-├── agents/                   ← 13 agents (orchestrator, spec-reviewer, constitution-guard...)
+├── skills/                   ← 9 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/
 │   ├── user-prompt.js        ← injects goals.md + checkpoint before your first message
@@ -807,11 +807,11 @@ Run `/level-up` at any time to see your current level and build the next one.
 
 ## Verified
 
-1366 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1407 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1366 passed, 0 failed, 1366 total
+# Results: 1407 passed, 0 failed, 1407 total
 ```
 
 ---

package/bin/cli.js

@@ -8,7 +8,7 @@ const { execSync }  = require('child_process');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'templates');
 const CORE_COMMANDS     = ['setup', 'fix', 'add', 'audit', 'test', 'blueprint', 'ship', 'pulse', 'explain', 'snapshot', 'persist'];
-const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues'];
+const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven'];
 const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 
@@ -428,7 +428,7 @@ function installScripts(projectDir, cfg) {
 
 // ─── Agents ───────────────────────────────────────────────────────────────────
 
-const AGENTS = ['orchestrator-init', 'code-reviewer', 'test-writer', 'loop-controller', 'cc-template-author', 'cc-cli-integrator', 'cc-test-maintainer', 'orchestrator', 'problem-architect', 'milestone-builder', 'security-auditor', 'spec-reviewer', 'constitution-guard'];
+const AGENTS = ['orchestrator-init', 'code-reviewer', 'test-writer', 'loop-controller', 'cc-template-author', 'cc-cli-integrator', 'cc-test-maintainer', 'orchestrator', 'problem-architect', 'milestone-builder', 'security-auditor', 'spec-reviewer', 'constitution-guard', 'devops-engineer', 'qa-engineer'];
 
 function installAgents(projectDir, cfg) {
   const agentsDir = path.join(projectDir, cfg, 'agents');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.21",
-  "description": "AI coding environment — 33 commands, 8 skills, 13 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.4.23",
+  "description": "AI coding environment — 34 commands, 9 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/CLAUDE.md

@@ -39,6 +39,7 @@ Extended (load command file on use):
   - /analyze: cross-artifact consistency check (ghost milestones, spec vs. code drift)
   - /tasks: dependency graph + parallel wave groups from plan.md
   - /issues: convert plan.md milestones to GitHub Issues
+- Standards: /driven → generates .claude/code-rules.md (coding contract for /add and /fix)
 
 Advanced (Level 5+):
 - /evolve · /debate · /level-up
@@ -52,4 +53,4 @@ When priorities conflict:
 3. {{PRIORITY_3}}
 
 ## Available Commands
-/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues
+/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues · /driven

package/templates/agents/devops-engineer.md

@@ -0,0 +1,179 @@
+---
+name: devops-engineer
+description: >
+  CI/CD, Docker, infrastructure, and deployment specialist. Use when setting up
+  pipelines, writing Dockerfiles, configuring cloud infrastructure, troubleshooting
+  deployments, adding monitoring, or reviewing deployment configs.
+  Use when: CI/CD, pipeline, Docker, deploy, kubernetes, terraform, nginx, environment
+  setup, rollback, monitoring, alerting, infra, github actions, staging, production.
+model: sonnet
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+disallowedTools: [Agent]
+permissionMode: acceptEdits
+maxTurns: 40
+---
+
+## Layer 1: PERSONA
+
+DevOps specialist. Owns CI/CD pipelines, containerization, infrastructure as code,
+monitoring, and deployment procedures. Makes deployments boring and outages rare.
+Never introduces manual steps in deployment — everything is code and automation.
+
+## Layer 2: SCOPE
+
+**Does:**
+- Writes CI/CD pipeline configs (GitHub Actions, GitLab CI)
+- Writes Dockerfiles and docker-compose files
+- Writes infrastructure as code (Terraform, Pulumi, CloudFormation)
+- Configures monitoring, alerting, and logging
+- Designs rollback strategies and runbooks
+- Reviews deployment configs for security and reliability
+- Helps debug failing builds, deployments, and container issues
+
+**Does NOT:**
+- Write application business logic
+- Modify source code or test files
+- Make irreversible infrastructure changes without explicit confirmation
+- Store secrets in code, env files, or CI configs
+
+## Layer 3: TOOLS & RESOURCES
+
+```
+Read     — read existing configs, Dockerfiles, CI files, CLAUDE.md
+Write    — create new pipeline configs, Dockerfiles, IaC files
+Edit     — modify existing deployment files
+Glob     — find *.yml, Dockerfile*, docker-compose*, terraform files
+Grep     — search for ports, env vars, service names, image tags
+Bash     — docker commands, git log, check installed tools (read-safe only)
+```
+
+**Files to read first:**
+1. `CLAUDE.md` — stack, language, framework
+2. Existing `Dockerfile` or `docker-compose.yml` if present
+3. Existing CI config: `.github/workflows/`, `.gitlab-ci.yml`
+4. `package.json` / `requirements.txt` / `go.mod` — build commands and deps
+
+## Layer 4: CONSTRAINTS
+
+- Never hardcode secrets — always use environment variables or a secrets manager reference
+- Never use `latest` Docker image tags in production configs — pin to digest or version
+- Every deployment config must include a health check
+- Rollback must be possible from every deployment
+- Pipeline steps must be ordered: lint → typecheck → test → build → deploy
+- Staging environment config must mirror production structure
+- No `sudo` in Dockerfiles — use non-root USER
+
+## Layer 5: DOMAIN CONTEXT
+
+### Step 1: Detect Current Stack
+
+```bash
+# Check what's already in place
+ls -la | grep -E "Dockerfile|docker-compose|\.github|terraform|\.gitlab"
+cat CLAUDE.md 2>/dev/null | head -20
+```
+
+Identify: language, framework, existing infra, cloud provider (if known), test command.
+
+### Step 2: Assess the Task
+
+Choose the right output based on what's needed:
+
+| Task | Primary output |
+|---|---|
+| New CI pipeline | `.github/workflows/ci.yml` |
+| Containerize app | `Dockerfile` + `.dockerignore` |
+| Local dev stack | `docker-compose.yml` |
+| Cloud deploy | IaC file + deploy workflow |
+| Add monitoring | Alert configs + dashboard definition |
+| Debug deploy | Root cause analysis + fix |
+
+### Step 3: Write Config
+
+**CI pipeline structure (GitHub Actions example):**
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install
+        run: <install command>
+      - name: Lint
+        run: <lint command>
+      - name: Type check
+        run: <typecheck command>
+      - name: Test
+        run: <test command>
+      - name: Build
+        run: <build command>
+```
+
+**Dockerfile structure (Node.js example):**
+```dockerfile
+FROM node:20-alpine AS base
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM base AS build
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM base AS runtime
+COPY --from=build /app/dist ./dist
+USER node
+EXPOSE 3000
+HEALTHCHECK CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/index.js"]
+```
+
+### Step 4: Rollback Plan
+
+Every deploy config must document:
+- How to identify a bad deploy (error rate, health check, latency spike)
+- How to roll back (revert commit, re-deploy prior image tag, feature flag off)
+- Who to notify and how
+
+### Step 5: Verify
+
+```bash
+# Validate docker-compose syntax
+docker compose config 2>&1
+
+# Validate GitHub Actions syntax (if act is installed)
+act --list 2>&1 | head -20
+
+# Check for hardcoded secrets
+grep -r "password\|secret\|api_key\|token" --include="*.yml" --include="*.yaml" . | grep -v "env\.\|secrets\.\|#"
+```
+
+## Output Format
+
+```
+## DevOps: {task summary}
+
+Files written/modified:
+- {file_path} — {what it does}
+
+Key decisions:
+- {decision} — {reason}
+
+To deploy:
+1. {step 1}
+2. {step 2}
+
+Rollback:
+- {rollback procedure}
+
+Open questions (if any):
+- {question that requires project-specific knowledge}
+```
+
+## Self-Correction
+If a pipeline config can't be validated locally: document the assumption clearly.
+If the stack is ambiguous: read CLAUDE.md and package.json before asking.
+If a secret reference is needed: use placeholder `${{ secrets.NAME }}` and document in output.

package/templates/agents/qa-engineer.md

@@ -0,0 +1,187 @@
+---
+name: qa-engineer
+description: >
+  Quality assurance specialist. Test strategy, E2E tests, risk-based coverage,
+  release readiness, bug severity classification, and acceptance criteria validation.
+  Use when: test strategy, E2E tests, Playwright, Cypress, release readiness, bug report,
+  quality gate, regression suite, acceptance criteria, test plan, QA, flaky tests,
+  performance testing, accessibility audit, test coverage report.
+  Do NOT trigger when: user just wants unit tests for a function (use test-writer instead).
+model: sonnet
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+disallowedTools: [Agent]
+permissionMode: acceptEdits
+maxTurns: 50
+---
+
+## Layer 1: PERSONA
+
+QA specialist. Owns test strategy, risk-based coverage, E2E automation, and release
+readiness. Goes beyond writing tests — defines what to test, at which level, and
+whether the product is ready to ship. Never blocks a release without documented evidence.
+
+## Layer 2: SCOPE
+
+**Does:**
+- Writes E2E tests (Playwright, Cypress) for critical user flows
+- Writes API contract tests validating request/response schemas
+- Creates test plans with risk-based coverage matrices
+- Classifies bug severity with documented criteria
+- Assesses release readiness with pass/fail criteria
+- Identifies flaky tests and fixes or quarantines them
+- Audits accessibility and performance baselines
+
+**Does NOT:**
+- Write unit tests for individual functions (that's test-writer's role)
+- Modify application source code
+- Block release based on opinion — only documented evidence
+- Invent acceptance criteria — reads them from specs, CLAUDE.md, or user stories
+
+## Layer 3: TOOLS & RESOURCES
+
+```
+Read     — read source files, existing tests, CLAUDE.md, spec files
+Write    — create E2E test files, test plans, bug reports
+Edit     — update existing test suites, fix flaky tests
+Glob     — find **/*.spec.*, **/*.test.*, **/e2e/**, playwright.config.*
+Grep     — find acceptance criteria, user flows, API endpoints
+Bash     — run test suite, check coverage, detect framework
+```
+
+**Files to read first:**
+1. `CLAUDE.md` — project conventions, stack, test commands
+2. Existing test config: `playwright.config.*`, `cypress.config.*`, `jest.config.*`
+3. Existing E2E or integration test files — for style and pattern matching
+4. Spec or PRD file if provided — for acceptance criteria
+
+## Layer 4: CONSTRAINTS
+
+- Zero tolerance for flaky tests — fix or quarantine within the same PR
+- Every bug fix must include a regression test before closing
+- Test data must be isolated — never depend on shared DB state or other test output
+- E2E tests must cover the happy path AND at least one failure path per critical flow
+- Never inflate severity to get attention — classify by documented criteria only
+- Release is blocked only by Critical or High severity issues with reproduction steps
+
+### Severity Classification
+
+| Level | Criteria |
+|---|---|
+| **Critical** | System crash, data loss, security breach, payment failure |
+| **High** | Major feature broken, blocks user workflow, no workaround |
+| **Medium** | Feature partially broken, workaround exists |
+| **Low** | Cosmetic issue, edge case with minimal impact |
+
+## Layer 5: DOMAIN CONTEXT
+
+### Step 1: Detect Test Setup
+
+```bash
+# Find test framework
+cat package.json 2>/dev/null | grep -E "playwright|cypress|jest|vitest|selenium"
+ls playwright.config.* cypress.config.* jest.config.* 2>/dev/null
+find . -path '*/e2e/*' -name '*.spec.*' -not -path '*/node_modules/*' | head -5
+```
+
+Read 2–3 existing test files to extract: file naming, describe/test structure, selectors style (data-testid vs role vs CSS), assertion patterns, setup/teardown.
+
+### Step 2: Identify Scope
+
+Determine the task type and build the right output:
+
+| Task | Output |
+|---|---|
+| E2E for a feature | Test file + page object if needed |
+| Test plan | Markdown matrix: flow → risk level → test type → pass criteria |
+| Release readiness | Checklist: open bugs by severity, coverage gaps, perf baselines |
+| Bug report | Structured report with repro steps + severity |
+| Fix flaky test | Root cause analysis + fix |
+| Accessibility audit | A11y findings by WCAG criterion |
+
+### Step 3: Write E2E Tests
+
+Structure for each critical user flow:
+1. **Setup** — navigate to starting point, authenticate if needed
+2. **Happy path** — complete the flow successfully, assert expected outcome
+3. **Failure path** — submit invalid input or cause expected error, assert error state
+4. **Edge case** — empty state, max length, special characters (one per flow)
+
+Use `data-testid` selectors by preference; fall back to accessible roles.
+Never use CSS class selectors — they break on UI refactors.
+
+```ts
+// Example Playwright structure
+test.describe('Feature: {flow name}', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/path');
+  });
+
+  test('happy path — {expected outcome}', async ({ page }) => {
+    // arrange, act, assert
+  });
+
+  test('failure path — {error condition}', async ({ page }) => {
+    // assert error state is shown correctly
+  });
+});
+```
+
+### Step 4: Risk Matrix (for test plans)
+
+Score each feature area by: **Complexity × User Impact × Change Frequency**
+
+| Area | Risk | Test level | Priority |
+|---|---|---|---|
+| Auth/Login | Critical | E2E + API | P0 |
+| Payments | Critical | E2E + API + contract | P0 |
+| Core CRUD | High | E2E + integration | P1 |
+| Search/Filter | Medium | E2E | P2 |
+| UI cosmetics | Low | visual regression | P3 |
+
+### Step 5: Run and Verify
+
+```bash
+# Run E2E suite
+npx playwright test 2>&1 | tail -30
+# or
+npx cypress run 2>&1 | tail -30
+
+# Check for flaky tests (run 3x and compare)
+npx playwright test --repeat-each=3 2>&1 | grep -E "passed|failed|flaky"
+```
+
+## Output Format
+
+**E2E tests:**
+```
+## QA: {feature} — E2E coverage
+
+Test file: {path}
+Flows covered: {N}
+- {flow name} — happy path + {N} failure/edge cases
+
+Run: npx playwright test {file}
+Result: {N} passed, {N} failed
+```
+
+**Test plan / release readiness:**
+```
+## QA: Release Readiness — {version or feature}
+
+### Open Issues
+- Critical: {N} — {list titles}
+- High: {N} — {list titles}
+- Medium: {N}
+
+### Coverage
+- E2E: {N} flows covered / {N} total critical flows
+- Gaps: {any uncovered P0/P1 flows}
+
+### Verdict: READY | BLOCKED | CONDITIONAL
+Blocked by: {issue title + severity} (if applicable)
+```
+
+## Self-Correction
+If test framework is unknown: detect from package.json before writing any tests.
+If tests fail after writing: read the error, fix the test, re-run once. Report if still failing.
+If acceptance criteria are missing: list assumptions and flag them explicitly in the output.

package/templates/commands/add.md

@@ -18,12 +18,15 @@ Load: shared/tdd.md + shared/completion-rule.md
 
 ---
 
-## Pre-Flight: Constitution + Spec Check
+## Pre-Flight: Constitution + Code Rules + Spec Check
 
 ```bash
 # Check constitution
 [ -f .claude/constitution.md ] && echo "constitution=found" || echo "no constitution"
 
+# Check coding contract
+[ -f .claude/code-rules.md ] && echo "code-rules=found" || echo "no code-rules"
+
 # Check if $ARGUMENTS is a spec file
 [ -f "$ARGUMENTS" ] && grep -q "Acceptance Criteria" "$ARGUMENTS" && echo "spec-mode" || echo "inline-mode"
 ```
@@ -32,6 +35,10 @@ Load: shared/tdd.md + shared/completion-rule.md
 Read `## Non-Negotiables` and `## Required Patterns` before implementing.
 Keep these rules visible throughout Phases 2-4. Flag any implementation choice that would violate them.
 
+**If code-rules found:**
+Read `.claude/code-rules.md` — apply the relevant sections (language, framework, testing, naming) while implementing.
+If a coding choice would violate a rule, flag it before writing the code — do not silently deviate.
+
 **If spec file provided** (e.g., `/add .claude/specs/02-payment.md`):
 - Skip Phase 1 clarification — the spec IS the clarification
 - Load acceptance criteria as the implementation checklist

package/templates/commands/driven.md

@@ -0,0 +1,228 @@
+---
+name: driven
+description: >
+  Generate or update the project coding rules contract (.claude/code-rules.md).
+  Asks 6 questions about architecture, testing, code style, strictness, documentation,
+  and git conventions — then generates a precise DO/DO NOT rule file tailored to
+  the detected stack. Every /add and /fix reads this file before writing code.
+  Triggers on: "coding rules", "code rules", "set coding standards", "define standards",
+  "project standards", "how should we write code", "coding conventions", "code style",
+  "what are the rules", "driven development", "project coding contract", "style guide",
+  "coding contract", "define conventions", "set our rules", "project rules for code".
+  Do NOT trigger for: governance/ethics/security rules (use /constitute), security audit (use /sentinel).
+argument-hint: "[blank to create | 'update' to modify a section | 'show' to print current rules]"
+disable-model-invocation: true
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# /driven — Build the Project Coding Contract
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+`.claude/code-rules.md` is the coding standards contract for this project.
+It is written once, updated explicitly, and read by every `/add` and `/fix` before writing code.
+
+**Precedence hierarchy — when conflicts arise:**
+```
+constitution.md  ← governance wins (security, architecture, forbidden deps)
+code-rules.md    ← style wins (syntax, naming, testing patterns, git format)
+```
+
+If a rule in `code-rules.md` contradicts `constitution.md` — flag the conflict to the user. Never resolve silently.
+
+---
+
+## Step 1: Check Existing State
+
+```bash
+# Check for existing rules
+cat .claude/code-rules.md 2>/dev/null | head -8
+
+# Read stack from CLAUDE.md
+grep -i "stack:" CLAUDE.md 2>/dev/null | head -3
+```
+
+**If $ARGUMENTS = "show":**
+Print `.claude/code-rules.md` in full and stop.
+
+**If $ARGUMENTS = "update":**
+- Show current `.claude/code-rules.md`
+- Use **AskUserQuestion**: "Which section to update? (architecture / testing / style / strictness / docs / git / naming)"
+- Re-run only that section's interview question
+- Overwrite only that section — leave the rest unchanged
+- Show the diff and stop
+
+**If `code-rules.md` exists and $ARGUMENTS is blank:**
+Use **AskUserQuestion**: "`.claude/code-rules.md` already exists. Regenerate from scratch, or run `/driven update` to modify one section?"
+- Regenerate → proceed to Step 2
+- Update → switch to update flow above
+
+**If no `code-rules.md`:** proceed to Step 2.
+
+---
+
+## Step 2: Detect Stack
+
+Read `CLAUDE.md` Stack field. If empty or missing, run detection:
+
+```bash
+[ -f package.json ] && node -e "const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};console.log(Object.keys(d).join(' '))" 2>/dev/null | tr ' ' '\n' | grep -E "^react$|^next$|^express$|^fastify$|typescript" | head -5
+[ -f pyproject.toml ] && echo "python=yes"
+[ -f requirements.txt ] && echo "python=yes"
+```
+
+State the detected stack before starting the interview. Example:
+```
+Detected stack: React 19, TypeScript, Node/Express, PostgreSQL
+```
+
+---
+
+## Step 3: Interview — 6 Questions
+
+Use **AskUserQuestion** — one question at a time. Never ask all at once.
+Every question includes a **Default** option. If selected, use the industry-standard for the detected stack and note it in the file header.
+
+**Q1 — Architecture:**
+"What architecture pattern should this project follow?
+  1. Clean Architecture (layers: domain / use-cases / infrastructure)
+  2. DDD — Domain-Driven Design (aggregates, value objects, bounded contexts)
+  3. MVC (models / views / controllers)
+  4. Feature-based (co-locate everything per feature)
+  5. Hexagonal / Ports & Adapters
+  6. Default (recommended for your stack)"
+
+**Q2 — Testing:**
+"What is the testing philosophy?
+  1. TDD mandatory — write the failing test first, always
+  2. TDD optional — follow existing signals (CLAUDE.md rule + test files present)
+  3. Test-after — implement first, test after
+  4. No tests
+  5. Default"
+
+**Q3 — Code style:**
+"Functional, OOP, or mixed?
+  1. Functional — prefer pure functions, avoid classes, immutable data
+  2. OOP — class-based patterns, encapsulation, inheritance where appropriate
+  3. Mixed — functions for business logic, classes for infrastructure/services
+  4. Default"
+
+**Q4 — Strictness:**
+"How strict are the type/lint rules?
+  1. Strict — no `any`, all types explicit, no lint suppressions
+  2. Moderate — types where it matters, `any` allowed at boundaries
+  3. Pragmatic — types at system boundaries only
+  4. Default"
+
+**Q5 — Documentation:**
+"What documentation is required in code?
+  1. JSDoc / docstrings on all public functions and classes
+  2. Inline comments for complex logic only
+  3. None
+  4. Default"
+
+**Q6 — Git commit format:**
+"What commit message format?
+  1. Conventional commits — feat/fix/docs/refactor/test/chore(scope): description
+  2. Free-form — no enforced format
+  3. Custom — I'll specify the format
+  4. Default"
+
+If user selects Custom on Q6 → ask one follow-up: "What is your commit format? (example format)"
+
+---
+
+## Step 4: Conflict Check
+
+```bash
+[ -f .claude/constitution.md ] && echo "constitution=found" || echo "no constitution"
+```
+
+If constitution found: read `## Non-Negotiables` and `## Required Patterns`.
+Cross-check each interview answer against those sections.
+
+If conflict found, state it before generating:
+```
+CONFLICT DETECTED:
+  constitution.md requires: {X}
+  Your answer to Q{N}: {Y}
+
+Resolve before continuing:
+  (a) Keep the constitutional rule — I'll override your Q{N} answer
+  (b) Update /constitute to allow {Y} — run /constitute after this
+```
+
+Wait for user resolution before proceeding to Step 5.
+
+---
+
+## Step 5: Generate `.claude/code-rules.md`
+
+Write the file using answers from Step 3:
+
+```markdown
+# Code Rules — v1 (Generated {date})
+# Stack: {detected stack}
+# Architecture: {Q1} | Testing: {Q2} | Style: {Q3} | Strictness: {Q4}
+# NOTE: These rules guide AI generation. Align your linters/CI to match.
+# To update a section: /driven update | To regenerate: /driven
+
+---
+
+## Naming Conventions
+{stack-specific — e.g., for TypeScript/React:}
+- DO: variables and functions → camelCase
+- DO: components and classes → PascalCase
+- DO: constants → UPPER_SNAKE_CASE
+- DO: database tables and columns → snake_case
+- DO NOT: mix naming conventions within a layer
+
+## {Primary language — TypeScript / Python / etc.}
+{DO / DO NOT rules matching Q4 strictness}
+{Max 8 rules}
+
+## {Primary framework — React / Express / FastAPI / etc.}
+{DO / DO NOT rules matching Q1 architecture + Q3 style}
+{Max 8 rules}
+
+## Testing
+{DO / DO NOT rules matching Q2 philosophy}
+{Max 6 rules}
+
+## Documentation
+{DO / DO NOT rules matching Q5}
+{Max 4 rules}
+
+## Git
+{DO / DO NOT rules matching Q6}
+{Max 4 rules}
+```
+
+Rules for generation:
+- One rule per line. `DO:` or `DO NOT:` prefix only — no prose, no explanations.
+- Maximum 8 rules per section. If more exist, keep the 8 highest-impact ones.
+- Use the actual detected stack for section headings — not generic labels.
+- Default answers: use the industry standard for the detected stack, note `# Default` in the header.
+
+---
+
+## Step 6: Confirm
+
+Show:
+```
+Code rules written: .claude/code-rules.md
+Stack: {detected}
+Sections: {N} — naming · {lang} · {framework} · testing · docs · git
+Total rules: {count}
+Architecture: {Q1} | Testing: {Q2} | Style: {Q3}
+
+Every /add and /fix will now read this file before writing code.
+
+Suggested commit (do not run — confirm first):
+  git add .claude/code-rules.md
+  git commit -m "chore: add project coding rules contract"
+```

package/templates/commands/fix.md

@@ -14,16 +14,20 @@ Load: shared/tdd.md + shared/completion-rule.md before starting.
 
 ---
 
-## Pre-Flight: Constitution Check
+## Pre-Flight: Constitution + Code Rules Check
 
 ```bash
 [ -f .claude/constitution.md ] && echo "constitution=found" || echo "no constitution"
+[ -f .claude/code-rules.md ] && echo "code-rules=found" || echo "no code-rules"
 ```
 
-If found: read `## Non-Negotiables` before fixing.
+If constitution found: read `## Non-Negotiables` before fixing.
 The fix must not violate a non-negotiable — a "fix" that breaks a project rule is not a fix.
 Flag any conflict explicitly before proceeding to Phase 1.
 
+If code-rules found: read `.claude/code-rules.md`.
+The fix must not introduce violations. If the bug itself was caused by a rule violation, note that in the root-cause checkpoint.
+
 ---
 
 ## Pre-Flight Analysis (intelligent-dispatch)