@thecodesaiyan/claude-dev-workflow-hook 1.0.0

package/AGENTS.md

@@ -0,0 +1,223 @@
+# AGENTS.md -- Development Workflow Protocol
+
+Follow these mandatory workflow rules for ALL implementation work.
+Violations (skipping tests, skipping planning, ignoring TDD) are NOT acceptable.
+
+## Compliance Reporting
+
+Announce rule adherence as you work. Before starting any task:
+
+1. State which rules apply (see the Quick Reference table at the bottom).
+2. Prefix each action with `[PROTOCOL Rule N]` as you execute it.
+3. If you skip a rule, state why (e.g. Rule 1 small-task exception).
+
+Example output:
+
+```
+[PROTOCOL Rule 0] Planning: This task modifies 4 files -- api.ts, schema.ts, UserForm.tsx, user.test.ts.
+[PROTOCOL Rule 1] Small task -- skipping team orchestration (2 files, no new entity).
+[PROTOCOL Rule 2] TDD RED: Writing failing test for createUser validation...
+[PROTOCOL Rule 3] Test loop: Running tests after schema.ts change...
+[PROTOCOL Rule 4] Phase 1: Researching affected files and dependency graph...
+[PROTOCOL Rule 5] UI check: Verifying responsive layout at 375px / 768px / 1024px...
+[PROTOCOL Rule 6] Integration test: Starting container stack...
+```
+
+If you do NOT output these prefixes, you are violating this protocol.
+
+## Rule 0 -- Plan Before Acting
+
+Before writing ANY code:
+
+1. Identify every file that will be created or modified.
+2. Map dependencies between changes (e.g. backend model change breaks frontend types).
+3. If more than 2 files are affected, create a detailed plan and get approval before proceeding.
+4. If the plan changes mid-implementation, STOP and revise the plan.
+
+## Rule 1 -- Small Task Exception
+
+If a task changes 2 or fewer files AND does not add a new entity or endpoint:
+
+- Skip team orchestration (Rule 4).
+- Still follow Rules 0, 2, 3 (plan, TDD, test loop).
+- Still follow Rule 5 if modifying frontend components.
+- Still follow Rule 6 if modifying API endpoints or services.
+- Still run the full test suite before marking done.
+
+## Rule 2 -- TDD Enforcement
+
+For new features and bug fixes:
+
+1. **RED** -- Write a failing test that describes the expected behavior.
+2. **GREEN** -- Write the minimum code to make the test pass.
+3. **IMPROVE** -- Refactor without changing behavior; re-run tests.
+4. Target 80%+ coverage.
+
+## Rule 3 -- Test After Every Change
+
+After EVERY code change (not just at the end):
+
+1. Run the relevant test suite for the area you changed.
+2. If ANY test fails, fix it BEFORE moving to the next change.
+3. Never stack multiple untested changes -- each change must pass before proceeding.
+4. After all changes, run the full test suite.
+
+### Auto-Detect Test Runner
+
+Use the first match found in the project root:
+
+| Indicator | Command |
+|-----------|---------|
+| `package.json` with `test` script | `npm test` / `yarn test` / `pnpm test` / `bun test` (match lockfile) |
+| `Makefile` with `test` target | `make test` |
+| `Cargo.toml` | `cargo test` |
+| `go.mod` | `go test ./...` |
+| `*.sln` or `*.slnx` | `dotnet test <solution-file>` |
+| `pyproject.toml` or `setup.py` | `pytest` or `python -m pytest` |
+| `build.gradle` or `pom.xml` | `./gradlew test` or `mvn test` |
+| `mix.exs` | `mix test` |
+| `Gemfile` | `bundle exec rspec` or `bundle exec rake test` |
+
+If multiple ecosystems exist (e.g. .NET backend + React frontend), run BOTH test suites.
+
+## Rule 4 -- Agent Team Orchestration (Multi-File Features)
+
+For features touching more than 2 files, use a 7-phase pipeline with maximum parallelism.
+Do NOT do all work inline -- delegate to agent teams or parallel workers where available.
+
+### Phase 1: Research (Read-Only) -- SEQUENTIAL
+
+Map the affected area before implementing:
+
+- Identify all affected files, existing patterns, test coverage, and the dependency graph.
+- Wait for the research to complete before proceeding.
+
+### Phase 2: Implementation -- PARALLEL WHERE POSSIBLE
+
+Maximize parallelism by partitioning work into file-isolated subsystems:
+
+1. Analyze Phase 1 output. Partition work so no two workers edit the same file
+   (concurrent edits to the same file cause overwrites).
+2. Track dependencies between tasks. Example:
+   ```
+   Task 1: Backend models (no deps) -- starts immediately
+   Task 2: Backend services (depends on 1)
+   Task 3: Frontend types (depends on 2 -- needs API contract)
+   Task 4: Frontend components (depends on 3)
+   Task 5: Backend tests (depends on 2)
+   Task 6: Frontend tests (depends on 4)
+   ```
+   When Task 2 completes, Tasks 3 AND 5 unblock in parallel -- maximum concurrency.
+3. Assign each subsystem to a separate worker (e.g., backend worker, frontend worker).
+4. Workers must know their assigned files AND which files not to touch.
+5. Follow TDD (Rule 2) and test after each file change (Rule 3).
+
+If parallel workers are not available, implement sequentially in dependency order:
+  - Backend: models -> services -> controllers/handlers -> middleware
+  - Frontend: types -> API client -> stores/hooks -> components -> pages
+  - Fullstack: backend first, then frontend consuming the new API
+
+### Phases 3 + 4 + 5: Review Team -- PARALLEL
+
+After Phase 2, perform three independent review passes in parallel.
+Reviewers should challenge each other's findings where possible.
+
+**Phase 3 -- Fact Check:**
+Verify all planned changes were implemented. Check API contracts -- request/response
+types must match between backend and frontend. Check i18n completeness.
+
+**Phase 4 -- Security and Quality Audit:**
+Audit for hardcoded secrets, unvalidated inputs, SQL injection, XSS vectors.
+Check for efficient queries and no N+1 patterns. Verify naming and file-structure conventions.
+
+**Phase 5 -- Readability and Consistency:**
+Review naming against existing patterns. Check for small functions, clear names,
+minimal nesting. Flag redundant comments or missing comments where logic is non-obvious.
+
+### Phase 6: Synthesis -- SEQUENTIAL
+
+After phases 3-5 complete:
+
+- Read all review outputs and fix any bugs, inconsistencies, or issues raised.
+- Run the full test suite one final time.
+
+### Phase 7: Finalize -- SEQUENTIAL
+
+- If the project uses containers: rebuild and verify all services are healthy.
+- Smoke-test the new feature (manual or automated).
+- Update project docs if the project tracks build status or feature summaries.
+
+### Phase Dependencies
+
+```
+Phase 1 (research)
+  -> Phase 2 (parallel implementation via workers OR sequential)
+    -> Phases 3 + 4 + 5 (parallel reviews)
+      -> Phase 6 (synthesis + fix + final tests)
+        -> Phase 7 (finalize)
+```
+
+### Enforcement
+
+- Never skip phases. If a phase finds no issues, report that it ran clean.
+- Report each phase with `[PROTOCOL Rule 4] Phase N: <description>...`
+
+## Rule 5 -- UI and Layout Standards
+
+When modifying frontend components:
+
+- **Responsive testing**: Verify at 375px (mobile), 768px (tablet), and 1024px (desktop).
+- **Layout stability**: No content overflow, clipped dropdowns, or scroll containers trapping positioned elements.
+- **Overflow rules**: Prefer `overflow-x-clip` over `overflow-hidden` when clipping without a scroll container. Never use `overflow-x-auto` on wrappers containing absolutely-positioned menus.
+- **Flexbox chain**: `h-screen` (root) -> `min-h-0` (flex items) -> `overflow-y-auto` (scrollable area).
+- **Accessibility**: Semantic HTML, keyboard navigation, visible focus indicators, sufficient color contrast.
+- **Consistency**: Follow the project's design system, color tokens, and component patterns.
+- **i18n**: If the project uses internationalization, all user-facing strings must go through the translation system. Update ALL locale files when adding keys.
+
+## Rule 6 -- Integration Testing
+
+When adding or modifying API endpoints, services, or middleware:
+
+### Container-First Testing (if applicable)
+
+1. Start the project's container stack BEFORE running tests.
+2. Verify all services are healthy.
+3. Test new endpoints against live containers first -- catches issues that mocks hide (constraint violations, nullable columns, auth middleware).
+4. Kill stale dev processes that may occupy the same ports.
+
+### Backend Integration Tests
+
+1. Use the project's test factory or fixture (e.g. WebApplicationFactory, TestServer, Supertest).
+2. Mock external dependencies: databases (in-memory/SQLite), caches (no-op), job queues (no-op), third-party APIs (mock HTTP).
+3. When adding new DI services, add corresponding test doubles in the test factory.
+4. When adding constructor dependencies, fix ALL test files that mock that service.
+5. Watch for global query filters, soft-delete scopes, or tenant isolation that behaves differently in test vs production.
+
+### Frontend Test Isolation
+
+1. Initialize i18n in test setup so translation keys resolve to readable strings.
+2. Mock API calls (MSW, manual mocks, test interceptors) -- never hit real endpoints from unit/integration tests.
+3. Test paginated API consumers: verify they handle the pagination wrapper (`.items`, `.data`, `.results`), not raw arrays.
+4. For data-fetching libraries (React Query, SWR, Apollo), wrap in the appropriate provider with a fresh client per test.
+
+### Common Pitfalls
+
+- In-memory database providers skip migrations, constraints, and triggers -- guard migration calls with provider checks.
+- Background job frameworks often need no-op storage set BEFORE the app starts in test mode.
+- WebApplicationFactory patterns may require a `public partial class Program { }` sentinel.
+- HTTP status codes matter for client interceptors (e.g. 401 may trigger auto-logout -- do not return 401 for validation errors).
+
+## Quick Reference
+
+| Situation | Required Rules |
+|-----------|---------------|
+| New entity + API + frontend | 0, 2, 3, 4 (full pipeline), 5, 6 |
+| Multi-file feature (>2 files) | 0, 2, 3, 4 + 5/6 if applicable |
+| Bug fix (1-2 files) | 0, 1, 2, 3 |
+| UI-only change (1-2 files) | 0, 1, 2, 3, 5 |
+| UI change (>2 files) | 0, 2, 3, 4, 5 |
+| Backend-only change (1-2 files) | 0, 1, 2, 3, 6 |
+| Backend change (>2 files) | 0, 2, 3, 4, 6 |
+| New API endpoint | 0, 1, 2, 3, 6 |
+| Refactor (>2 files) | 0, 3, 4 + full test suite before AND after |
+| Refactor (1-2 files) | 0, 1, 3 + full test suite before AND after |

package/README.md

@@ -0,0 +1,352 @@
+# Claude Code Development Workflow Hook
+
+## Purpose
+
+A `SessionStart` hook that injects a structured development workflow protocol once per Claude Code session. It enforces planning, TDD, recursive testing, UI standards, agent team orchestration, and integration testing — automatically, project-agnostically.
+
+> **Why SessionStart?** The protocol injects once per session (on startup, resume, clear, and compact) rather than on every prompt. This saves significant context window budget over long conversations. `SessionStart` supports `additionalContext` injection via `hookSpecificOutput`.
+
+## Language / Stack
+
+- **Languages:** Node.js (primary), Python 3 (alternative)
+- **Runtime:** Claude Code CLI hook system (`SessionStart` event)
+- **Platforms:** Windows, macOS, Linux
+- **Dependencies:** None (Node.js built-ins only / Python stdlib only)
+
+## AGENTS.md (Platform-Agnostic Version)
+
+This tool also ships an `AGENTS.md` file — a portable, plain-Markdown version of the same workflow protocol that works with **any AI coding agent** (GitHub Copilot, Cursor, Codex, Google Jules, and [20+ other platforms](https://agents.md)).
+
+### How to use it
+
+Copy `AGENTS.md` into the root of any repository where you want agents to follow the protocol:
+
+```bash
+cp AGENTS.md /path/to/your/project/AGENTS.md
+```
+
+That's it. No hooks, no installer, no authority binding — agents that support the [AGENTS.md standard](https://agents.md) will read it automatically.
+
+### When to use which
+
+| Approach | Best for | How it works |
+|----------|----------|--------------|
+| **Hook** (Node.js or Python) | Claude Code users | Injected once per session via `SessionStart` + CLAUDE.md authority binding |
+| **AGENTS.md** | Any AI agent | Placed at repo root; agents read it as project context automatically |
+
+You can use both — they contain the same rules. The hook enforces via injection; the AGENTS.md file relies on the agent reading it from the repo.
+
+### Nested AGENTS.md
+
+For monorepos, place an AGENTS.md in subdirectories to override or extend the root rules. The closest file to the edited code takes precedence.
+
+## What's Inside
+
+7 mandatory rules wrapped in `<dev-workflow-protocol>` XML tags with compliance reporting:
+
+| Rule | Name | Purpose |
+|------|------|---------|
+| 0 | Plan Before Acting | Identify files, map dependencies, enter Plan Mode if >2 files |
+| 1 | Small Task Exception | Skip team orchestration for <=2 file changes (still TDD + test) |
+| 2 | TDD Enforcement | RED -> GREEN -> IMPROVE cycle, 80%+ coverage target |
+| 3 | Test After Every Change | Run tests after EVERY change, never stack untested changes |
+| 4 | Agent Team Orchestration | 7-phase pipeline with parallel implementation via Agent Teams (subagent fallback) |
+| 5 | UI & Layout Standards | Responsive testing, overflow rules, accessibility, i18n |
+| 6 | Integration Testing | Container-first testing, backend/frontend test isolation |
+
+The **Compliance Reporting** section requires the model to prefix actions with `[PROTOCOL Rule N]`, making rule adherence visible.
+
+## Prerequisites
+
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
+- **Node.js 18+** (for npm install) OR **Python 3** (for Python install)
+
+---
+
+## Install via npm (Recommended)
+
+Single command — no clone needed:
+
+**Global install** (all projects):
+
+```bash
+npx @thecodesaiyan/claude-dev-workflow-hook --global
+```
+
+**Per-project install** (current project only):
+
+```bash
+npx @thecodesaiyan/claude-dev-workflow-hook --project
+```
+
+### Uninstall via npm
+
+```bash
+npx @thecodesaiyan/claude-dev-workflow-hook --uninstall --scope global
+npx @thecodesaiyan/claude-dev-workflow-hook --uninstall --scope project
+```
+
+---
+
+## Install via Python (Alternative)
+
+If you prefer Python or don't have Node.js:
+
+### From a local clone
+
+```bash
+git clone https://github.com/ntatschner/ai-utilities.git
+cd ai-utilities/tools/claude-dev-workflow-hook
+```
+
+Then run the installer:
+
+**Global install** (all projects):
+
+```bash
+# macOS / Linux
+python3 install.py --global
+
+# Windows
+py install.py --global
+```
+
+**Per-project install** (current project only):
+
+```bash
+# macOS / Linux
+python3 install.py --project
+
+# Windows
+py install.py --project
+```
+
+**Interactive** (prompts you):
+
+```bash
+# macOS / Linux
+python3 install.py
+
+# Windows
+py install.py
+```
+
+### Remote one-liner
+
+**macOS / Linux:**
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/ntatschner/ai-utilities/main/tools/claude-dev-workflow-hook/install-remote.sh) --global
+```
+
+**Windows (PowerShell):**
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ntatschner/ai-utilities/main/tools/claude-dev-workflow-hook/install-remote.ps1" -OutFile "$env:TEMP\install-remote.ps1"; & "$env:TEMP\install-remote.ps1" -Scope Global
+```
+
+### Uninstall via Python
+
+```bash
+# macOS / Linux
+python3 install.py --uninstall --scope global    # or --scope project
+
+# Windows
+py install.py --uninstall --scope global          # or --scope project
+```
+
+---
+
+## What the installer does
+
+Both the npm and Python installers perform the same 4 steps:
+
+```
+[1/4] Copying hook script
+  OK: Copied session-start.js -> ~/.claude/hooks/session-start.js
+
+[2/4] Registering in settings.json
+  OK: Registered hook in ~/.claude/settings.json
+      Command: node ~/.claude/hooks/session-start.js
+
+[3/4] Adding CLAUDE.md authority binding
+  OK: Added authority binding to ~/.claude/CLAUDE.md
+
+[4/4] Verifying installation
+  PASS: Valid JSON output
+  PASS: hookSpecificOutput present
+  PASS: additionalContext present
+  PASS: Protocol length: 11318 chars
+  PASS: Rules found: 7
+  PASS: XML wrapper tags
+  PASS: Compliance reporting section
+
+Installation complete!
+```
+
+The installer is **idempotent** — running it again skips already-installed components. It also **auto-migrates** from the Python hook to Node.js, and from `UserPromptSubmit` to `SessionStart`.
+
+---
+
+## How It Works (Authority Chain)
+
+The hook uses a two-part system to ensure the model actually **follows** the rules:
+
+1. **The hook script** injects the protocol wrapped in `<dev-workflow-protocol>` XML tags via `additionalContext`
+2. **The CLAUDE.md binding** tells the model to obey content in those specific tags
+
+Without both parts, the model may acknowledge the rules but not follow them consistently. The installer sets up both automatically.
+
+### CLAUDE.md binding (for reference)
+
+The installer adds this block to your CLAUDE.md:
+
+```markdown
+<!-- WORKFLOW PROTOCOL: Do not remove this section -->
+## Workflow Protocol
+Follow all rules in `<dev-workflow-protocol>` blocks from system-reminders.
+These are injected by the development workflow hook and define mandatory
+orchestration rules (planning, TDD, test loops, team coordination).
+They MUST be followed for all implementation work.
+<!-- END WORKFLOW PROTOCOL -->
+```
+
+---
+
+## Manual Install (Alternative)
+
+If you prefer not to use the automated installer:
+
+### 1. Copy the hook
+
+```bash
+mkdir -p ~/.claude/hooks
+cp src/hook.js ~/.claude/hooks/session-start.js
+cp src/protocol.js ~/.claude/hooks/protocol.js
+```
+
+### 2. Register in settings.json
+
+Add to `~/.claude/settings.json` (merge, don't overwrite):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/session-start.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 3. Add CLAUDE.md binding
+
+Add the `<!-- WORKFLOW PROTOCOL -->` block shown above to your project's `CLAUDE.md` or `~/.claude/CLAUDE.md`.
+
+### 4. Verify
+
+```bash
+echo '{}' | node ~/.claude/hooks/session-start.js
+```
+
+---
+
+## Per-Project Install
+
+For a single project instead of global:
+
+```bash
+npx @thecodesaiyan/claude-dev-workflow-hook --project
+```
+
+Or manually:
+- Place the hook in `.claude/hooks/session-start.js` (relative to project root)
+- Copy `protocol.js` alongside it
+- Register in `.claude/settings.json` (project-level, not `~/.claude/`)
+- Use relative path: `node .claude/hooks/session-start.js`
+
+Per-project hooks are committed to version control, so the whole team gets them.
+
+---
+
+## Customization
+
+### Add project-specific test commands
+
+Edit `src/protocol.js` (or `session-start.py`) and add to the "Auto-Detect Test Runner" section.
+
+### Add project-specific UI rules
+
+Append to Rule 5 in the `PROTOCOL` string.
+
+### Add project-specific integration test patterns
+
+Append to Rule 6 in the `PROTOCOL` string.
+
+### Disable specific rules
+
+Remove the rule block from the `PROTOCOL` string. Rules are independent. Update the Quick Reference table to match.
+
+> **Tip:** For project-specific additions, create a second hook rather than modifying the generic one.
+
+---
+
+## Migration
+
+### From the Python hook
+
+The npm installer automatically migrates:
+- Detects `session-start.py` under `SessionStart` and replaces with `session-start.js`
+- No manual steps needed — just run `npx @thecodesaiyan/claude-dev-workflow-hook --global`
+
+### From the UserPromptSubmit version
+
+Both installers automatically migrate:
+- Remove the old `UserPromptSubmit` entry
+- Register under `SessionStart` instead
+- The new registration injects once per session instead of on every prompt
+
+### From the Bash version
+
+1. Run `npx @thecodesaiyan/claude-dev-workflow-hook --global`
+2. Remove the old bash hook entry from `settings.json`
+3. Delete `~/.claude/hooks/session-start.sh`
+
+---
+
+## Troubleshooting
+
+### "node: not found"
+
+Install Node.js 18+ from [nodejs.org](https://nodejs.org/).
+
+### "python3: not found" / "py: not found"
+
+- **macOS:** `brew install python3`
+- **Linux:** `apt install python3` or `dnf install python3`
+- **Windows:** Install from [python.org](https://www.python.org/downloads/) (includes `py` launcher)
+
+### Model acknowledges rules but doesn't follow them
+
+Missing CLAUDE.md authority binding. Run the installer again or add it manually (see above).
+
+### Model doesn't show `[PROTOCOL Rule N]` prefixes
+
+1. Verify the hook is injecting: ask "What workflow rules are active?"
+2. Verify the CLAUDE.md binding exists
+3. Add `"You MUST show [PROTOCOL Rule N] prefixes for EVERY action"` to your CLAUDE.md
+
+### Multiple hooks conflicting
+
+`SessionStart` hooks run in array order. Each hook's `additionalContext` is concatenated. If you see duplicate rules, consolidate into a single hook.
+
+### Hook doesn't run
+
+1. Verify `settings.json` is valid JSON (no trailing commas)
+2. Check the path matches where you placed the script
+3. Restart Claude Code after modifying `settings.json`

package/bin/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CLI entry point for @thecodesaiyan/claude-dev-workflow-hook
+ *
+ * Usage:
+ *   npx @thecodesaiyan/claude-dev-workflow-hook --global
+ *   npx @thecodesaiyan/claude-dev-workflow-hook --project
+ *   npx @thecodesaiyan/claude-dev-workflow-hook --uninstall --scope global
+ */
+
+const { install, getClaudeHome, getProjectClaude } = require('../src/installer.js');
+const { uninstall } = require('../src/uninstaller.js');
+const { bold } = require('../src/utils.js');
+
+function printUsage() {
+  console.log(bold('Claude Code Development Workflow Hook'));
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx @thecodesaiyan/claude-dev-workflow-hook --global     Install globally (~/.claude/)');
+  console.log('  npx @thecodesaiyan/claude-dev-workflow-hook --project    Install in current project (.claude/)');
+  console.log('  npx @thecodesaiyan/claude-dev-workflow-hook --uninstall --scope global');
+  console.log('  npx @thecodesaiyan/claude-dev-workflow-hook --uninstall --scope project');
+  console.log('  npx @thecodesaiyan/claude-dev-workflow-hook --help       Show this help');
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const result = {
+    global: false,
+    project: false,
+    uninstall: false,
+    scope: null,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--global':
+        result.global = true;
+        break;
+      case '--project':
+        result.project = true;
+        break;
+      case '--uninstall':
+        result.uninstall = true;
+        break;
+      case '--scope':
+        result.scope = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        result.help = true;
+        break;
+      default:
+        console.error(`Unknown argument: ${args[i]}`);
+        printUsage();
+        process.exit(1);
+    }
+  }
+
+  return result;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  console.log(bold('Claude Code Development Workflow Hook'));
+  console.log(`Node.js: ${process.version} | Platform: ${process.platform}`);
+
+  if (args.uninstall) {
+    if (!args.scope) {
+      console.error('Error: --uninstall requires --scope (global or project)');
+      printUsage();
+      process.exit(1);
+    }
+    if (!['global', 'project'].includes(args.scope)) {
+      console.error(`Error: --scope must be 'global' or 'project', got: '${args.scope}'`);
+      process.exit(1);
+    }
+    const targetDir = args.scope === 'global' ? getClaudeHome() : getProjectClaude();
+    uninstall(targetDir);
+    return;
+  }
+
+  if (args.global && args.project) {
+    console.error('Error: --global and --project are mutually exclusive');
+    process.exit(1);
+  }
+
+  if (!args.global && !args.project) {
+    console.error('Error: specify --global or --project');
+    printUsage();
+    process.exit(1);
+  }
+
+  const scopeIsGlobal = args.global;
+  const targetDir = scopeIsGlobal ? getClaudeHome() : getProjectClaude();
+  install(targetDir, scopeIsGlobal);
+}
+
+main();