glori-builder 1.0.0

package/.claude/commands/project-setup.md

@@ -0,0 +1,187 @@
+---
+description: One-time repository setup — creates GitHub Actions CI, sets branch protection, creates project CLAUDE.md. Run once per new project.
+---
+
+# Project Setup
+
+Sets up a repository to work with the quetrex-base pipeline. Run once per project, not once per developer.
+
+## Pre-flight
+
+1. Verify git repo: `git status` — must be in a git repo
+2. Verify gh auth: `gh auth status` — must be authenticated
+3. Get repo info: `gh repo view --json name,owner,defaultBranchRef`
+4. Confirm with user: "Setting up {owner}/{name}. Default branch: {branch}. Proceed?"
+
+## Step 1: GitHub Actions CI
+
+Create `.github/workflows/quality-gate.yml`:
+
+```bash
+mkdir -p .github/workflows
+```
+
+Write the file with this exact content:
+
+```yaml
+name: Quality Gate
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run type-check
+      - run: npm run lint
+
+  test:
+    name: Unit & Integration Tests
+    runs-on: ubuntu-latest
+    needs: quality
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test -- --coverage
+
+  build:
+    name: Production Build
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+```
+
+## Step 2: Branch Protection
+
+Set branch protection on main requiring CI to pass before merge:
+
+```bash
+gh api repos/{owner}/{repo}/branches/main/protection \
+  --method PUT \
+  --field required_status_checks='{"strict":true,"contexts":["Lint & Type Check","Unit & Integration Tests","Production Build"]}' \
+  --field enforce_admins=false \
+  --field required_pull_request_reviews='{"required_approving_review_count":0}' \
+  --field restrictions=null
+```
+
+If this fails (e.g. free GitHub account), warn the user and continue — it's not fatal.
+
+## Step 3: Project CLAUDE.md and Decisions Log
+
+Check if `.claude/CLAUDE.md` already exists:
+
+```bash
+[ -f .claude/CLAUDE.md ] && echo "exists" || echo "missing"
+```
+
+**If missing:** Create a minimal placeholder:
+```bash
+mkdir -p .claude
+cat > .claude/CLAUDE.md << 'EOF'
+# Project: {repo-name}
+
+## Stack
+Run /create-rules to generate the full stack configuration.
+
+## Workflow
+- All work on feature branches — never commit to main
+- PRs require CI to pass before merge
+- Use /issue-prd {ISSUE-ID} to start work on a Linear issue
+EOF
+```
+
+**If exists:** Check if it has a `## Verification` section:
+```bash
+grep -q "## Verification" .claude/CLAUDE.md && echo "has verification" || echo "missing verification"
+```
+
+If the Verification section is missing, note it in the summary — the user should run `/update-rules` after setup.
+
+Also create `.claude/decisions.md` if it doesn't exist:
+
+```bash
+[ -f .claude/decisions.md ] || cat > .claude/decisions.md << 'EOF'
+# Project Decisions
+
+Architectural decisions that affect how this project is built.
+The architect agent updates this file. All agents read it.
+
+<!-- Format for new entries:
+## YYYY-MM-DD — Short title
+**Decision**: what was decided
+**Reason**: why
+**Impact**: what it affects going forward
+-->
+EOF
+```
+
+## Step 4: direnv .envrc
+
+Check if direnv is installed:
+
+```bash
+which direnv 2>/dev/null && echo "installed" || echo "missing"
+```
+
+If installed and `.envrc` does not already exist:
+
+```bash
+echo 'dotenv' > .envrc
+direnv allow .
+```
+
+This tells direnv to load the project's `.env` file automatically when anyone enters the directory — database URLs, project API tokens, and other credentials become available to all commands (including Claude's) without manual sourcing.
+
+If `.envrc` already exists, skip. If direnv is not installed, skip and note it in the summary.
+
+## Step 5: Commit and Push
+
+```bash
+git add .github/workflows/quality-gate.yml .claude/CLAUDE.md
+[ -f .envrc ] && git add .envrc
+git commit -m "chore: project setup — CI, branch protection, CLAUDE.md, direnv"
+git push origin main
+```
+
+## Confirm
+
+Report:
+> "Project setup complete.
+> - CI: .github/workflows/quality-gate.yml created
+> - Branch protection: main requires Lint & Type Check, Unit & Integration Tests, Production Build
+> - CLAUDE.md: {created with placeholder / already existed}
+> - direnv: {.envrc created / already existed / direnv not installed — run /quetrex-setup}
+>
+> Next: run /create-rules to set up your stack configuration and verification commands."
+>
+> Partners can clone and start working immediately after: npm install -g @quetrex/base"
+
+## Notes
+- Run from the project root
+- Only the repo owner needs to run this — collaborators who clone get everything automatically
+- Branch protection requires a paid GitHub account for private repos
+- direnv loads project .env automatically — without it, database and service credentials must be manually exported before each session
+- Customize quality-gate.yml for your stack (e.g. add Playwright if you have E2E tests)

package/.claude/commands/quetrex-docs.md

@@ -0,0 +1,188 @@
+---
+description: Display the full quetrex-base reference — pipeline, commands, agents, setup requirements, and workflow. Run at the start of any session to orient Claude or share with a new partner.
+---
+
+# Quetrex Docs
+
+Display the complete quetrex-base system reference.
+
+---
+
+## The System
+
+Quetrex-base is a Claude Code workflow system for software development teams. It provides:
+- A structured pipeline from Linear issue to merged PR
+- Specialized agents for each stage of development
+- Commands for planning, setup, secrets management, and deployment
+- Cross-platform support (macOS, Linux, Windows WSL)
+
+---
+
+## Setup (run once per machine)
+
+```
+/quetrex-setup     Configure gh auth, git identity, Linear API key, direnv
+```
+
+## Setup (run once per project)
+
+```
+/project-setup     GitHub Actions CI, branch protection, direnv .envrc
+/create-rules      Generate .claude/CLAUDE.md with stack and verification commands
+/deploy-setup      Generate a project-specific /deploy skill
+```
+
+For existing projects with an existing CLAUDE.md:
+```
+/update-rules      Audit and fix existing .claude/CLAUDE.md for quetrex compatibility
+```
+
+---
+
+## The Development Pipeline
+
+```
+/issue-prd → architect → developer(s) → QA → reviewer → git-workflow → /merge-issue
+```
+
+**Greenfield — manual:**
+```
+/plan-project → Linear project + issues created → /issue-prd QUE-1 (work one at a time)
+```
+
+**Greenfield — auto-pilot (walk away):**
+```
+/plan-project → Linear project + issues created → /auto-pilot PROJECT-ID
+             → works every issue through full pipeline → auto-merges → done
+```
+
+**Brownfield (existing issue):**
+```
+/issue-prd QUE-123 → pipeline runs → PR created → /merge-issue QUE-123
+```
+
+**Rework (tester feedback):**
+```
+/issue-rework QUE-123 → rework document → pipeline reruns
+```
+
+---
+
+## All Commands
+
+### Pipeline
+
+| Command | What it does |
+|---|---|
+| `/issue-prd QUE-123` | Fetch Linear issue, evaluate, create feature branch, start pipeline |
+| `/issue-rework QUE-123` | Create rework document from tester feedback, restart pipeline |
+| `/merge-issue QUE-123` | Merge PR, update Linear status to Human Review |
+| `/auto-pilot PROJECT-ID` | Work entire Linear project backlog autonomously — walk away mode |
+
+### Planning
+
+| Command | What it does |
+|---|---|
+| `/plan-project` | Greenfield: interview → PRD → Linear project + all issues |
+| `/plan-feature` | Brownfield: codebase analysis + implementation plan |
+
+### Setup
+
+| Command | What it does |
+|---|---|
+| `/quetrex-setup` | One-time machine setup (gh auth, git config, Linear key, direnv) |
+| `/project-setup` | One-time project setup (CI, branch protection, .envrc) |
+| `/create-rules` | Generate project .claude/CLAUDE.md from stack templates |
+| `/update-rules` | Audit and update existing project .claude/CLAUDE.md |
+| `/deploy-setup` | Generate project-specific deploy skill (Fly.io, Vercel, etc.) |
+
+### Keys and Secrets
+
+| Command | What it does |
+|---|---|
+| `/secrets add KEY [--project]` | Add API key to ~/.claude/secrets.env or project .env |
+| `/secrets list` | Show configured key names (never values) |
+| `/secrets remove KEY [--project]` | Remove a key |
+
+### Maintenance
+
+| Command | What it does |
+|---|---|
+| `/quetrex-update` | Check for and apply updates to quetrex-base |
+| `/quetrex-docs` | Display this reference |
+
+### Utilities
+
+| Command | What it does |
+|---|---|
+| `/commit` | Create a commit for current changes |
+| `/prime` | Prime agent with codebase understanding |
+| `/execute` | Execute an implementation plan |
+| `/create-rules` | Already listed above |
+
+---
+
+## All Agents
+
+| Agent | Model | Role |
+|---|---|---|
+| `architect` | Opus | Implementation plan, file ownership map, acceptance criteria |
+| `developer` | Sonnet | Implementation + tests for one assigned workstream |
+| `qa` | Sonnet | Runs verification chain, reports actual exit codes |
+| `reviewer` | Opus | Semantic review of full diff — logic, security, architecture |
+| `git-workflow` | Haiku | Commit, push, squash PR to main |
+| `designer` | Sonnet | UI design spec (orchestrator decides when to invoke) |
+| `database-architect` | Sonnet | Schema design and migrations |
+| `product-manager` | Sonnet | Requirements gathering when issue lacks detail |
+| `security-reviewer` | Opus | OWASP security audit — read-only, invoked explicitly |
+| `test-writer` | Sonnet | Adds test coverage to existing code (utility, not pipeline) |
+| `nextjs-migrator` | Sonnet | Next.js major version upgrades |
+
+---
+
+## Branching Strategy
+
+```
+main
+  └── feature/QUE-123-description        ← one per issue
+        ├── feature/QUE-123-api          ← parallel developer A
+        ├── feature/QUE-123-db           ← parallel developer B
+        └── feature/QUE-123-ui           ← parallel developer C
+```
+
+- Sub-branches merge regularly into issue branch
+- Issue branch squash-merges into main via PR
+- All work on feature branches — never commit directly to main
+
+---
+
+## Multiple Linear Workspaces
+
+```bash
+# Global default (primary workspace)
+~/.claude/secrets.env → export LINEAR_API_KEY="lin_api_..."
+
+# Project-specific override (different workspace)
+project/.env → LINEAR_API_KEY=lin_api_other_workspace
+```
+
+---
+
+## Prerequisites
+
+| Requirement | Check | Install |
+|---|---|---|
+| GitHub CLI | `gh auth status` | `gh auth login` |
+| Linear API key | `/secrets list` | `/quetrex-setup` |
+| direnv | `which direnv` | `brew install direnv` / `apt install direnv` |
+| Node.js 18+ | `node --version` | nodejs.org |
+
+---
+
+## Partner Onboarding
+
+```bash
+npm install -g @quetrex/base   # installs agents, skills, commands
+/quetrex-setup                 # one-time machine config
+git clone <repo-url>           # project already has CI and rules
+```

package/.claude/commands/quetrex-setup.md

@@ -0,0 +1,159 @@
+---
+description: One-time machine setup for quetrex-base. Configures GitHub auth, git identity, and API keys. Run once per machine — partners run this after installing the npm package.
+---
+
+# Quetrex Setup
+
+Sets up your machine to run the quetrex-base pipeline. Run once per machine, not once per project.
+
+## Step 1: GitHub CLI
+
+```bash
+gh auth status 2>&1
+```
+
+If not authenticated, stop and tell the user:
+> "GitHub CLI is not authenticated. Run `gh auth login` in your terminal, choose GitHub.com and HTTPS, then run /quetrex-setup again."
+
+## Step 2: Git Identity
+
+```bash
+git config --global user.name
+git config --global user.email
+```
+
+If either is empty, ask the user for the missing value(s) and set them:
+
+```bash
+git config --global user.name "NAME"
+git config --global user.email "EMAIL"
+```
+
+## Step 3: secrets.env
+
+Check if the global secrets file exists:
+
+```bash
+[ -f ~/.claude/secrets.env ] && echo "exists" || echo "missing"
+```
+
+If missing, create it:
+
+```bash
+cat > ~/.claude/secrets.env << 'EOF'
+#!/bin/bash
+# quetrex-base secrets — never commit this file
+# Add to your shell profile: source ~/.claude/secrets.env
+EOF
+chmod 600 ~/.claude/secrets.env
+```
+
+`chmod 600` makes the file readable only by you — not other users on the machine.
+
+## Step 4: LINEAR_API_KEY
+
+Check which workspaces are already configured:
+
+```bash
+grep "LINEAR" ~/.claude/secrets.env 2>/dev/null || echo "none"
+```
+
+Display what's configured. Then ask:
+
+> "What Linear workspaces do you need? For each one, I need a name (e.g. 'personal', 'dealerq', 'client-x') and API key from Linear → Settings → API → Personal API Keys.
+>
+> Start with your primary workspace — you can add more with /secrets add later."
+
+For each workspace the user provides:
+
+- If it's the primary (first) workspace: add as `LINEAR_API_KEY`
+- If it's a named workspace: add as `LINEAR_{NAME}_API_KEY` (uppercased)
+
+Write to `~/.claude/secrets.env`:
+
+```bash
+# Append primary key
+echo '' >> ~/.claude/secrets.env
+echo '# Linear: primary workspace' >> ~/.claude/secrets.env
+echo 'export LINEAR_API_KEY="VALUE"' >> ~/.claude/secrets.env
+
+# Append named workspace key (if provided)
+echo '# Linear: NAME workspace' >> ~/.claude/secrets.env
+echo 'export LINEAR_NAME_API_KEY="VALUE"' >> ~/.claude/secrets.env
+```
+
+## Step 5: Shell Profile
+
+Check if secrets.env is already sourced:
+
+```bash
+grep -l "secrets.env" ~/.zshrc ~/.bashrc ~/.bash_profile ~/.profile 2>/dev/null | head -1
+```
+
+If not found in any profile, show the user exactly what to add and where:
+
+> "Add this line to your shell profile. For zsh (macOS default): `~/.zshrc`. For bash: `~/.bashrc`.
+>
+> ```
+> source ~/.claude/secrets.env
+> ```
+>
+> Then run: `source ~/.zshrc` (or open a new terminal)."
+
+If already sourced, confirm and skip.
+
+## Step 6: direnv (recommended)
+
+direnv automatically loads a project's `.env` file when you enter its directory. This means database URLs, project API keys, and other credentials are available to Claude's commands without any manual setup or per-command sourcing.
+
+Check if direnv is installed:
+
+```bash
+which direnv 2>/dev/null && direnv version || echo "not installed"
+```
+
+If not installed, recommend it:
+
+> "direnv is not installed. It's strongly recommended — without it, database commands and other project-specific credentials may fail silently.
+>
+> Install:
+> - macOS: `brew install direnv`
+> - Linux / Windows WSL: `sudo apt install direnv` or `curl -sfL https://direnv.net/install.sh | bash`
+>
+> After installing, add the hook to your shell profile:
+> - zsh: `echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc`
+> - bash: `echo 'eval "$(direnv hook bash)"' >> ~/.bashrc`
+>
+> Then: `source ~/.zshrc` and run /quetrex-setup again."
+
+If installed, check if the hook is in the shell profile:
+
+```bash
+grep -l "direnv hook" ~/.zshrc ~/.bashrc ~/.bash_profile 2>/dev/null | head -1
+```
+
+If the hook is missing, show the user the command to add it. If already configured, confirm and continue.
+
+**How direnv works with projects:** When a project has a `.env` file and an `.envrc` file containing `dotenv`, direnv auto-exports those vars whenever you `cd` into the directory. Claude's bash commands inherit them — no manual sourcing needed. The `/project-setup` command creates the `.envrc` file.
+
+## Step 7: Confirm
+
+```bash
+source ~/.claude/secrets.env 2>/dev/null
+echo "LINEAR_API_KEY : ${LINEAR_API_KEY:+set (${#LINEAR_API_KEY} chars)}"
+echo "gh auth        : $(gh auth status --active 2>&1 | head -1)"
+echo "git name       : $(git config --global user.name)"
+echo "git email      : $(git config --global user.email)"
+echo "direnv         : $(which direnv 2>/dev/null && direnv version || echo 'not installed')"
+```
+
+Report clearly what is set and what is missing. If everything is green:
+
+> "quetrex-base setup complete. You're ready to use /issue-prd, /plan-project, and the full pipeline."
+
+## Notes
+
+- LINEAR_API_KEY is your primary workspace default — used unless a project .env overrides it
+- Named workspace keys (LINEAR_DEALERQ_API_KEY etc.) are selected by /secrets when working in that project
+- Run /secrets to add keys, list what is configured, or switch a project to a named workspace
+- This file is read-only to other users (chmod 600) — do not put it in any git repo

package/.claude/commands/quetrex-update.md

@@ -0,0 +1,59 @@
+---
+description: Check for and apply updates to quetrex-base. Shows current vs latest version and updates if behind.
+---
+
+# Quetrex Update
+
+## Step 1: Check Installed Version
+
+```bash
+npm list -g @quetrex/base --depth=0 --json 2>/dev/null
+```
+
+Extract the installed version from the JSON output.
+
+If `@quetrex/base` is not found in the output, tell the user: "quetrex-base does not appear to be installed globally. Install it with: `npm install -g @quetrex/base`" and stop.
+
+## Step 2: Check Latest Version
+
+```bash
+npm show @quetrex/base version 2>/dev/null
+```
+
+## Step 3: Compare
+
+If installed == latest:
+> "You're on the latest version of quetrex-base (v{version}). Nothing to do."
+
+Clear the flag file if it exists: `rm -f ~/.claude/.quetrex-update-available`
+
+Stop.
+
+If installed != latest, display:
+> "quetrex-base update available
+> Installed: v{installed}
+> Latest:    v{latest}
+>
+> This will update all agents, skills, and commands in ~/.claude/.
+> Your settings.json permissions and custom project files will not be overwritten.
+> Update now?"
+
+Wait for confirmation before proceeding.
+
+## Step 4: Apply Update
+
+```bash
+npm install -g @quetrex/base@latest
+```
+
+The postinstall script runs automatically and copies all updated files to `~/.claude/`.
+
+## Step 5: Confirm
+
+```bash
+rm -f ~/.claude/.quetrex-update-available
+npm list -g @quetrex/base --depth=0
+```
+
+Report:
+> "Updated to v{latest}. Restart Claude Code to load new agents and skills."