claudeforge-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +431 -0
  3. package/bin/cli.js +155 -0
  4. package/package.json +43 -0
  5. package/src/commands/add.js +205 -0
  6. package/src/commands/create.js +218 -0
  7. package/src/commands/github.js +479 -0
  8. package/src/commands/init.js +107 -0
  9. package/src/commands/project.js +123 -0
  10. package/src/commands/status.js +183 -0
  11. package/src/commands/upgrade.js +114 -0
  12. package/src/index.js +6 -0
  13. package/src/logger.js +90 -0
  14. package/src/scaffolder.js +45 -0
  15. package/src/stack-detector.js +62 -0
  16. package/templates/.env.example.tpl +21 -0
  17. package/templates/.gitignore.tpl +40 -0
  18. package/templates/CLAUDE.local.md.tpl +32 -0
  19. package/templates/CLAUDE.md.tpl +112 -0
  20. package/templates/claude/README.md.tpl +94 -0
  21. package/templates/claude/agents/code-reviewer.md.tpl +142 -0
  22. package/templates/claude/commands/commit.md.tpl +34 -0
  23. package/templates/claude/commands/explain-codebase.md.tpl +37 -0
  24. package/templates/claude/commands/fix-issue.md.tpl +43 -0
  25. package/templates/claude/commands/memory-sync.md.tpl +49 -0
  26. package/templates/claude/commands/project-health.md.tpl +70 -0
  27. package/templates/claude/commands/review-pr.md.tpl +43 -0
  28. package/templates/claude/commands/scaffold-structure.md.tpl +308 -0
  29. package/templates/claude/commands/setup-project.md.tpl +253 -0
  30. package/templates/claude/commands/standup.md.tpl +34 -0
  31. package/templates/claude/hooks/post-tool-use.sh.tpl +44 -0
  32. package/templates/claude/hooks/pre-tool-use.sh.tpl +64 -0
  33. package/templates/claude/rules/no-sensitive-files.md.tpl +29 -0
  34. package/templates/claude/settings.json.tpl +50 -0
  35. package/templates/claude/settings.local.json.tpl +4 -0
  36. package/templates/claude/skills/project-conventions/SKILL.md.tpl +39 -0
  37. package/templates/mcp.json.tpl +9 -0
  38. package/templates/memory/MEMORY.md.tpl +37 -0
  39. package/templates/memory/feedback_communication.md.tpl +29 -0
  40. package/templates/memory/project_ai_workflow.md.tpl +43 -0
  41. package/templates/memory/user_profile.md.tpl +30 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vaibhav Jain
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,431 @@
1
+ # claudeforge
2
+
3
+ > Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/claudeforge)](https://www.npmjs.com/package/claudeforge)
6
+ [![PyPI version](https://img.shields.io/pypi/v/claudeforge)](https://pypi.org/project/claudeforge)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
9
+ [![Python 3.8+](https://img.shields.io/badge/python-%3E%3D3.8-blue)](https://python.org)
10
+
11
+ **No API key required.** Works with any Claude model — GitHub Copilot, Claude.ai, or any IDE with the Claude Code extension.
12
+
13
+ ---
14
+
15
+ ## Table of Contents
16
+
17
+ - [What It Does](#what-it-does)
18
+ - [Install](#install)
19
+ - [Quick Start](#quick-start)
20
+ - [CLI Commands](#cli-commands)
21
+ - [create](#create--interactive-wizard)
22
+ - [init](#init--scaffold-project-structure)
23
+ - [project](#project--prepare-ai-context)
24
+ - [add](#add--scaffold-agents-commands-skills)
25
+ - [github](#github--cicd--devcontainer)
26
+ - [status](#status--show-whats-configured)
27
+ - [upgrade](#upgrade--update-built-in-templates)
28
+ - [Slash Commands (in IDE chat)](#slash-commands-in-ide-chat)
29
+ - [What Gets Scaffolded](#what-gets-scaffolded)
30
+ - [How It Works](#how-it-works)
31
+ - [Troubleshooting](#troubleshooting)
32
+
33
+ ---
34
+
35
+ ## What It Does
36
+
37
+ `claudeforge` gives you a production-ready Claude Code setup:
38
+
39
+ - **Interactive wizard** (`create`) — go from zero to a fully configured project in one command
40
+ - **9 slash commands** for your daily workflow — `/setup-project`, `/commit`, `/review-pr`, `/scaffold-structure`, `/standup`, `/fix-issue`, `/explain-codebase`, `/project-health`, `/memory-sync`
41
+ - **A thorough code-reviewer agent** that checks correctness, security, performance, test coverage, style, and documentation
42
+ - **GitHub Actions CI/CD** auto-generated for your stack (Node, Python, Go, Rust)
43
+ - **VS Code devcontainer** with the Claude Code extension pre-configured
44
+ - **Hook scripts** that block dangerous operations before they run
45
+ - **A memory system** that persists project context across every Claude session
46
+
47
+ ---
48
+
49
+ ## Install
50
+
51
+ ### via npm (recommended)
52
+
53
+ ```bash
54
+ npm install -g claudeforge
55
+ ```
56
+
57
+ ### via pip
58
+
59
+ ```bash
60
+ pip install claudeforge
61
+ ```
62
+
63
+ > **pip users:** Node.js 18+ must be on your PATH. The pip package delegates to the Node.js CLI automatically.
64
+
65
+ Verify installation:
66
+
67
+ ```bash
68
+ claudeforge --version
69
+ ```
70
+
71
+ ---
72
+
73
+ ## Quick Start
74
+
75
+ ### Option A — Interactive wizard (fastest)
76
+
77
+ ```bash
78
+ claudeforge create my-api
79
+ ```
80
+
81
+ Walks you through project name, description, stack, and optional features (CI/CD, devcontainer, Docker). Then runs everything automatically.
82
+
83
+ ### Option B — Manual setup
84
+
85
+ ```bash
86
+ # 1. Go to your project directory
87
+ cd my-project
88
+
89
+ # 2. Scaffold the Claude Code structure
90
+ claudeforge init
91
+
92
+ # 3. Generate CI/CD and devcontainer
93
+ claudeforge github
94
+
95
+ # 4. Prepare AI context (detects your tech stack automatically)
96
+ claudeforge project "FastAPI REST API with PostgreSQL and Redis"
97
+
98
+ # 5. Open the project in VS Code / JetBrains / any IDE with Claude Code
99
+ # 6. In the Claude Code chat window, run:
100
+ # /setup-project "FastAPI REST API with PostgreSQL and Redis"
101
+
102
+ # Claude will fill in CLAUDE.md, settings, agents, commands, and memory
103
+ # tailored to your exact stack — no manual editing required.
104
+
105
+ # 7. Then run:
106
+ # /scaffold-structure
107
+ # to create src/, tests/, and starter files for your stack.
108
+ ```
109
+
110
+ ---
111
+
112
+ ## CLI Commands
113
+
114
+ ### `create` — Interactive wizard
115
+
116
+ ```bash
117
+ claudeforge create my-api
118
+ claudeforge create # prompts for name
119
+ claudeforge create --dir ~/Projects
120
+ ```
121
+
122
+ Walks you through:
123
+
124
+ 1. Project name
125
+ 2. Description (used by Claude to AI-configure everything)
126
+ 3. Tech stack selection
127
+ 4. Optional features: GitHub Actions CI/CD, devcontainer, Docker files
128
+
129
+ Then runs `init`, `project`, and `github` automatically — one command from zero to fully configured.
130
+
131
+ ---
132
+
133
+ ### `init` — Scaffold project structure
134
+
135
+ ```bash
136
+ claudeforge init
137
+ claudeforge init --dir ./my-project
138
+ claudeforge init --dry-run # preview without writing
139
+ claudeforge init --force # overwrite existing files
140
+ ```
141
+
142
+ Creates 25 files across the full Claude Code structure. Run this once per project.
143
+
144
+ **What gets created:**
145
+
146
+ | Path | Purpose |
147
+ |------|---------|
148
+ | `.claude/settings.json` | Team-shared permissions, model, hooks |
149
+ | `.claude/settings.local.json` | Personal overrides (gitignored) |
150
+ | `.claude/agents/code-reviewer.md` | 7-category code review agent |
151
+ | `.claude/commands/` | 9 slash commands (see below) |
152
+ | `.claude/hooks/pre-tool-use.sh` | Blocks rm -rf, curl\|bash, .env edits |
153
+ | `.claude/hooks/post-tool-use.sh` | Reminds to run tests after edits |
154
+ | `.claude/rules/no-sensitive-files.md` | Rule: don't touch secrets |
155
+ | `.claude/skills/project-conventions/` | Style skill loaded before writing code |
156
+ | `memory/MEMORY.md` | Index — always loaded by Claude |
157
+ | `memory/user_profile.md` | Your role and preferences (gitignored) |
158
+ | `memory/feedback_communication.md` | How Claude should behave |
159
+ | `memory/project_ai_workflow.md` | AI conventions for this project |
160
+ | `CLAUDE.md` | Project context template |
161
+ | `CLAUDE.local.md` | Personal context (gitignored) |
162
+ | `.mcp.json` | MCP servers (context7 pre-configured) |
163
+ | `.env.example` | Environment variable documentation |
164
+ | `.gitignore` | Covers secrets, local settings, OS artifacts |
165
+
166
+ ---
167
+
168
+ ### `project` — Prepare AI context
169
+
170
+ ```bash
171
+ claudeforge project "describe your project in plain English"
172
+ ```
173
+
174
+ Detects your tech stack from existing files (`package.json`, `go.mod`, `requirements.txt`, etc.), writes a `SETUP_CONTEXT.md` with full context, and tells you the exact command to run in Claude Code chat.
175
+
176
+ ```bash
177
+ # Examples
178
+ claudeforge project "Next.js SaaS with Stripe, Prisma, and Clerk auth"
179
+ claudeforge project "Go gRPC microservice with PostgreSQL and Redis cache"
180
+ claudeforge project "Django REST API with Celery, RabbitMQ, and S3"
181
+ claudeforge project "Rust CLI tool for parsing and transforming CSV files"
182
+ ```
183
+
184
+ After running, open Claude Code and run `/setup-project "your description"` in chat.
185
+
186
+ ---
187
+
188
+ ### `add` — Scaffold agents, commands, skills
189
+
190
+ ```bash
191
+ # Add a specialized agent
192
+ claudeforge add agent <name> [--description "..."] [--model sonnet|opus|haiku] [--color blue]
193
+
194
+ # Add a slash command
195
+ claudeforge add command <name> [--description "..."]
196
+
197
+ # Add a skill
198
+ claudeforge add skill <name> [--description "..."] [--no-user-invocable]
199
+ ```
200
+
201
+ ```bash
202
+ # Real examples
203
+ claudeforge add agent sql-reviewer \
204
+ --description "Reviews SQL migrations for safety, performance, and rollback safety"
205
+
206
+ claudeforge add command deploy \
207
+ --description "Run pre-deploy checks, deploy to staging, run smoke tests"
208
+
209
+ claudeforge add skill api-conventions \
210
+ --description "Apply REST API naming and response conventions before writing endpoints"
211
+ ```
212
+
213
+ | Flag | Description |
214
+ |------|-------------|
215
+ | `--description <text>` | Frontmatter description (important — determines when Claude invokes it) |
216
+ | `-f, --force` | Overwrite if file already exists |
217
+ | `-d, --dir <path>` | Target directory |
218
+ | `--model <model>` | (agent only) model override |
219
+ | `--color <color>` | (agent only) color in Claude UI |
220
+ | `--no-user-invocable` | (skill only) Claude-only, not user-invocable |
221
+
222
+ ---
223
+
224
+ ### `github` — CI/CD & devcontainer
225
+
226
+ ```bash
227
+ claudeforge github
228
+ claudeforge github --dry-run # preview without writing
229
+ claudeforge github --stack python # force stack detection
230
+ claudeforge github --no-devcontainer # skip devcontainer
231
+ ```
232
+
233
+ Auto-detects your stack and generates:
234
+
235
+ | Path | Purpose |
236
+ |------|---------|
237
+ | `.github/workflows/ci.yml` | Lint, test, build on push/PR |
238
+ | `.github/pull_request_template.md` | Structured PR checklist |
239
+ | `.github/ISSUE_TEMPLATE/bug_report.md` | Bug report template |
240
+ | `.github/ISSUE_TEMPLATE/feature_request.md` | Feature request template |
241
+ | `.github/CODEOWNERS` | Ownership file |
242
+ | `.devcontainer/devcontainer.json` | VS Code devcontainer with Claude Code |
243
+
244
+ CI workflows are generated for: **Node.js**, **Python**, **Go**, **Rust**, and **generic**.
245
+
246
+ ---
247
+
248
+ ### `status` — Show what's configured
249
+
250
+ ```bash
251
+ claudeforge status
252
+ claudeforge status --dir ./my-project
253
+ ```
254
+
255
+ Prints a full summary:
256
+
257
+ ```
258
+ Core Files ✓ 8/8 present
259
+ Settings Model: claude-sonnet-4-6 | 13 allowed, 4 denied | 2 hooks
260
+ MCP Servers context7, postgres
261
+ Agents (3) code-reviewer, api-reviewer, db-reviewer
262
+ Slash Commands 9 commands configured
263
+ Skills (2) project-conventions, api-conventions
264
+ Memory (4 files) ● 3 filled ○ 1 empty template
265
+ ```
266
+
267
+ ---
268
+
269
+ ### `upgrade` — Update built-in templates
270
+
271
+ ```bash
272
+ claudeforge upgrade # update hooks, rules, built-in commands
273
+ claudeforge upgrade --dry-run # preview changes
274
+ claudeforge upgrade --all # also update CLAUDE.md, settings.json, agents (⚠ overwrites edits)
275
+ ```
276
+
277
+ By default, only **infrastructure files** are updated (hook scripts, rules, built-in slash commands). Your edited files (`CLAUDE.md`, `settings.json`, custom agents) are untouched.
278
+
279
+ ---
280
+
281
+ ## Slash Commands (in IDE chat)
282
+
283
+ Run these in the Claude Code chat window in VS Code, JetBrains, or any Claude Code IDE. Works with any Claude model — no separate API key.
284
+
285
+ ### Setup & Maintenance
286
+
287
+ | Command | When to run | What it does |
288
+ |---------|-------------|-------------|
289
+ | `/setup-project "description"` | After `claudeforge init` | Fills in CLAUDE.md, settings, .env.example, .mcp.json, memory, generates 2–4 project-specific agents and commands, then documents every file it creates |
290
+ | `/scaffold-structure` | After `/setup-project` | Creates the actual `src/`, `tests/`, `cmd/` directory structure with real starter files for your stack |
291
+ | `/project-health` | Weekly / after big changes | Audits your setup: checks CLAUDE.md completeness, hook coverage, memory fill level, and gives prioritized improvement suggestions |
292
+ | `/memory-sync` | End of work session | Reviews the session and updates `memory/` files with preferences, decisions, and project context |
293
+
294
+ ### Daily Development
295
+
296
+ | Command | When to run | What it does |
297
+ |---------|-------------|-------------|
298
+ | `/commit` | After completing a feature | Reads `git diff`, stages relevant files, writes a conventional commit message |
299
+ | `/review-pr` | Before opening a PR | Reviews the branch diff — correctness, security, tests, style — with severity ratings |
300
+ | `/fix-issue "error message"` | When something breaks | Locates the bug, forms a hypothesis, makes a minimal targeted fix, verifies with tests |
301
+ | `/standup ["last 3 days"]` | Morning standup | Generates a concise update from recent git commits and open PRs |
302
+ | `/explain-codebase ["area"]` | Onboarding / exploring | Explains architecture, key flows, and what to read first |
303
+
304
+ ---
305
+
306
+ ## What Gets Scaffolded
307
+
308
+ ### `code-reviewer` Agent (7 categories)
309
+
310
+ Reviews changed code across:
311
+ 1. **Correctness** — logic errors, edge cases, async issues
312
+ 2. **Security** — hardcoded secrets, injection, path traversal, SSRF
313
+ 3. **Error Handling** — swallowed errors, missing timeouts, resource leaks
314
+ 4. **Performance** — N+1 queries, unbounded growth, blocking calls
315
+ 5. **Test Coverage** — happy path, error paths, edge cases, assertions
316
+ 6. **Style** — naming, magic numbers, dead code, DRY
317
+ 7. **Documentation** — missing docstrings, stale docs, changelog
318
+
319
+ Returns: `✓ LGTM` / `~ LGTM with suggestions` / `⚠ Address warnings` / `✗ Needs changes`
320
+
321
+ ### Hook Scripts (auto-`chmod 755`)
322
+
323
+ **`pre-tool-use.sh`** blocks before every tool call:
324
+ - `rm -rf` on absolute paths outside `/tmp`
325
+ - Editing `.env`, credentials, key files (warns first)
326
+ - `curl | bash` and `wget | sh` patterns
327
+
328
+ **`post-tool-use.sh`** injects reminders:
329
+ - Prompts to run tests after editing test files
330
+
331
+ ### Memory System
332
+
333
+ Four structured memory files — Claude reads them every session:
334
+
335
+ | File | What it stores | Gitignored? |
336
+ |------|---------------|-------------|
337
+ | `MEMORY.md` | Index of all memory files | No |
338
+ | `user_profile.md` | Your role, background, preferences | Yes |
339
+ | `feedback_communication.md` | How Claude should behave | No |
340
+ | `project_ai_workflow.md` | AI conventions for this project | No |
341
+
342
+ ---
343
+
344
+ ## How It Works
345
+
346
+ ```
347
+ ┌─────────────────────────────┐ ┌──────────────────────────────┐
348
+ │ Terminal CLI │ │ Claude Code (IDE chat) │
349
+ │ │ │ │
350
+ │ create my-api ────────────┼─────┼▶ init + project + github │
351
+ │ │ │ │
352
+ │ init ────────────┼─────┼▶ .claude/ structure created │
353
+ │ project "..." ────────────┼─────┼▶ SETUP_CONTEXT.md written │
354
+ │ github ────────────┼─────┼▶ CI/CD + devcontainer │
355
+ │ │ │ │
356
+ │ │◀────┼─ /setup-project "..." │
357
+ │ │ │ ↳ fills CLAUDE.md │
358
+ │ │ │ ↳ updates settings.json │
359
+ │ │ │ ↳ creates agents │
360
+ │ │ │ ↳ creates commands │
361
+ │ │ │ ↳ documents every file │
362
+ │ │ │ │
363
+ │ │◀────┼─ /scaffold-structure │
364
+ │ │ │ ↳ creates src/, tests/ │
365
+ │ │ │ ↳ writes starter files │
366
+ │ │ │ │
367
+ │ add agent ... ────────────┼─────┼▶ template created │
368
+ │ status ────────────┼─────┼▶ summary printed │
369
+ │ upgrade ────────────┼─────┼▶ hooks/rules updated │
370
+ └─────────────────────────────┘ └──────────────────────────────┘
371
+ ```
372
+
373
+ The CLI handles file scaffolding. The AI work happens inside the IDE where Claude has full tool access to read, write, and run commands — no separate API key needed.
374
+
375
+ ---
376
+
377
+ ## Troubleshooting
378
+
379
+ **`claudeforge: command not found`**
380
+ ```bash
381
+ # npm
382
+ npm install -g claudeforge
383
+ # pip (ensure ~/.local/bin is on PATH)
384
+ pip install claudeforge
385
+ export PATH="$HOME/.local/bin:$PATH"
386
+ ```
387
+
388
+ **pip install: `Node.js is required`**
389
+ ```bash
390
+ # macOS
391
+ brew install node
392
+ # Ubuntu/Debian
393
+ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
394
+ sudo apt-get install -y nodejs
395
+ ```
396
+
397
+ **`/setup-project` didn't generate anything**
398
+ Make sure you ran `claudeforge init` first — the `.claude/commands/` directory must exist for slash commands to work.
399
+
400
+ **Hook scripts not running**
401
+ ```bash
402
+ # Verify hooks are executable
403
+ ls -la .claude/hooks/
404
+ # Re-apply execute permission
405
+ chmod 755 .claude/hooks/*.sh
406
+ # Re-run init to restore hooks
407
+ claudeforge init --force
408
+ ```
409
+
410
+ **`claudeforge upgrade` overwrote my custom changes**
411
+ Only use `--all` flag when you want to reset user-owned files. Without `--all`, only infrastructure files (hooks, rules, built-in commands) are updated.
412
+
413
+ **Slash commands not showing in IDE**
414
+ Confirm you're running Claude Code (not just Copilot Chat). The `.claude/commands/` directory must be in the project root. Restart the IDE after running `init`.
415
+
416
+ ---
417
+
418
+ ## Requirements
419
+
420
+ | Requirement | Version | Notes |
421
+ |-------------|---------|-------|
422
+ | Node.js | 18+ | Required for the CLI |
423
+ | npm | any | Included with Node.js |
424
+ | Python | 3.8+ | Only if installing via pip |
425
+ | Claude Code | latest | IDE extension for slash commands |
426
+
427
+ ---
428
+
429
+ ## License
430
+
431
+ MIT
package/bin/cli.js ADDED
@@ -0,0 +1,155 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const { program } = require('commander');
5
+ const { version } = require('../package.json');
6
+ const initCommand = require('../src/commands/init');
7
+ const projectCommand = require('../src/commands/project');
8
+ const { addAgent, addCommand, addSkill } = require('../src/commands/add');
9
+ const statusCommand = require('../src/commands/status');
10
+ const upgradeCommand = require('../src/commands/upgrade');
11
+ const createCommand = require('../src/commands/create');
12
+ const githubCommand = require('../src/commands/github');
13
+
14
+ program
15
+ .name('claudeforge')
16
+ .description('Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command')
17
+ .version(version);
18
+
19
+ // ── init ─────────────────────────────────────────────────────────────────────
20
+ program
21
+ .command('init')
22
+ .description('Scaffold the Claude Code project structure (.claude/, memory/, CLAUDE.md, etc.)')
23
+ .option('-f, --force', 'Overwrite existing files without prompting')
24
+ .option('-n, --dry-run', 'Preview what would be created without writing anything')
25
+ .option('-d, --dir <path>', 'Target directory (defaults to current directory)')
26
+ .action(initCommand);
27
+
28
+ // ── project ───────────────────────────────────────────────────────────────────
29
+ program
30
+ .command('project <description>')
31
+ .description('Prepare your project for AI setup — writes SETUP_CONTEXT.md and guides you to run /setup-project in the Claude Code chat')
32
+ .option('-d, --dir <path>', 'Target directory (defaults to current directory)')
33
+ .addHelpText('after', `
34
+ No API key required. Works with any Claude model you already have access to
35
+ (GitHub Copilot, Claude.ai, or any IDE with the Claude Code extension).
36
+
37
+ Examples:
38
+ $ claudeforge project "FastAPI REST API with PostgreSQL and Redis"
39
+ $ claudeforge project "React + Tailwind dashboard with Supabase and Stripe"
40
+ $ claudeforge project "Go microservice for payment processing" --dir ./my-service
41
+
42
+ After running this, open the project in your IDE and run:
43
+ /setup-project "your description"
44
+ in the Claude Code chat window.
45
+ `)
46
+ .action(projectCommand);
47
+
48
+ // ── add ──────────────────────────────────────────────────────────────────────
49
+ const addCmd = program
50
+ .command('add')
51
+ .description('Scaffold a new agent, slash command, or skill');
52
+
53
+ addCmd
54
+ .command('agent <name>')
55
+ .description('Create a new sub-agent in .claude/agents/')
56
+ .option('-d, --dir <path>', 'Target directory')
57
+ .option('-f, --force', 'Overwrite if already exists')
58
+ .option('--description <text>', 'Agent description (shown in frontmatter)')
59
+ .option('--model <model>', 'Agent model: sonnet | opus | haiku', 'sonnet')
60
+ .option('--color <color>', 'Agent color in Claude UI', 'blue')
61
+ .addHelpText('after', `
62
+ Example:
63
+ $ claudeforge add agent sql-reviewer --description "Reviews SQL migrations for safety"
64
+ `)
65
+ .action(addAgent);
66
+
67
+ addCmd
68
+ .command('command <name>')
69
+ .description('Create a new slash command in .claude/commands/')
70
+ .option('-d, --dir <path>', 'Target directory')
71
+ .option('-f, --force', 'Overwrite if already exists')
72
+ .option('--description <text>', 'Command description (shown in command palette)')
73
+ .addHelpText('after', `
74
+ Example:
75
+ $ claudeforge add command deploy --description "Deploy the app to staging"
76
+ `)
77
+ .action(addCommand);
78
+
79
+ addCmd
80
+ .command('skill <name>')
81
+ .description('Create a new skill in .claude/skills/<name>/SKILL.md')
82
+ .option('-d, --dir <path>', 'Target directory')
83
+ .option('-f, --force', 'Overwrite if already exists')
84
+ .option('--description <text>', 'Skill trigger description')
85
+ .option('--no-user-invocable', 'Make this a Claude-only skill (user-invocable: false)')
86
+ .addHelpText('after', `
87
+ Example:
88
+ $ claudeforge add skill api-conventions --description "Apply REST API naming conventions"
89
+ `)
90
+ .action(addSkill);
91
+
92
+ // ── status ────────────────────────────────────────────────────────────────────
93
+ program
94
+ .command('status')
95
+ .description('Show what is configured in this Claude Code project')
96
+ .option('-d, --dir <path>', 'Target directory (defaults to current directory)')
97
+ .action(statusCommand);
98
+
99
+ // ── upgrade ───────────────────────────────────────────────────────────────────
100
+ program
101
+ .command('upgrade')
102
+ .description('Update infrastructure templates (hooks, rules, skills) to the latest version')
103
+ .option('-d, --dir <path>', 'Target directory (defaults to current directory)')
104
+ .option('-n, --dry-run', 'Preview what would change without writing anything')
105
+ .option('--all', 'Also update user-owned files (CLAUDE.md, settings.json, agents, commands) — WILL overwrite your edits')
106
+ .addHelpText('after', `
107
+ By default, only infrastructure files are updated:
108
+ .claude/hooks/*, .claude/rules/*, .claude/skills/project-conventions/*, memory/MEMORY.md
109
+
110
+ User-owned files (CLAUDE.md, .claude/settings.json, agents, commands, .mcp.json) are left untouched
111
+ unless you pass --all.
112
+ `)
113
+ .action(upgradeCommand);
114
+
115
+ // ── create ────────────────────────────────────────────────────────────────────
116
+ program
117
+ .command('create [name]')
118
+ .description('Interactive wizard — scaffold a new AI-powered project from scratch')
119
+ .option('-d, --dir <path>', 'Parent directory to create the project in (defaults to current directory)')
120
+ .addHelpText('after', `
121
+ Walks you through project name, description, stack selection, and optional
122
+ features (CI/CD, devcontainer, GitHub templates). Then runs init + project
123
+ automatically — one command to go from zero to a fully configured Claude project.
124
+
125
+ Example:
126
+ $ claudeforge create my-api
127
+ $ claudeforge create # prompts for name
128
+ `)
129
+ .action(createCommand);
130
+
131
+ // ── github ────────────────────────────────────────────────────────────────────
132
+ program
133
+ .command('github')
134
+ .description('Generate GitHub Actions CI/CD, PR templates, issue templates, and devcontainer')
135
+ .option('-d, --dir <path>', 'Target directory (defaults to current directory)')
136
+ .option('-n, --dry-run', 'Preview what would be created without writing anything')
137
+ .option('--stack <stack>', 'Force a stack: node | python | go | rust | generic')
138
+ .option('--no-devcontainer', 'Skip .devcontainer/ generation')
139
+ .option('--no-pr-template', 'Skip pull_request_template.md')
140
+ .option('--no-issue-templates','Skip issue templates')
141
+ .addHelpText('after', `
142
+ Auto-detects your stack and generates:
143
+ .github/workflows/ci.yml — lint, test, build on push/PR
144
+ .github/pull_request_template.md — structured PR checklist
145
+ .github/ISSUE_TEMPLATE/ — bug report + feature request templates
146
+ .github/CODEOWNERS — ownership file (placeholder)
147
+ .devcontainer/devcontainer.json — VS Code devcontainer with Claude Code
148
+
149
+ Examples:
150
+ $ claudeforge github
151
+ $ claudeforge github --stack python --no-devcontainer
152
+ `)
153
+ .action(githubCommand);
154
+
155
+ program.parse(process.argv);
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "claudeforge-cli",
3
+ "version": "1.0.0",
4
+ "description": "Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command",
5
+ "bin": {
6
+ "claudeforge": "bin/cli.js"
7
+ },
8
+ "main": "./src/index.js",
9
+ "files": [
10
+ "bin/",
11
+ "src/",
12
+ "templates/",
13
+ "README.md"
14
+ ],
15
+ "scripts": {
16
+ "test": "node --test src/**/*.test.js",
17
+ "link": "npm link",
18
+ "start": "node bin/cli.js"
19
+ },
20
+ "keywords": [
21
+ "claudeforge",
22
+ "claude",
23
+ "claude-code",
24
+ "anthropic",
25
+ "scaffold",
26
+ "ai",
27
+ "agents",
28
+ "cli",
29
+ "boilerplate",
30
+ "devcontainer",
31
+ "github-actions"
32
+ ],
33
+ "author": "Vaibhav Jain",
34
+ "license": "MIT",
35
+ "engines": {
36
+ "node": ">=18.0.0"
37
+ },
38
+ "dependencies": {
39
+ "chalk": "4.1.2",
40
+ "commander": "^12.1.0",
41
+ "fs-extra": "^11.2.0"
42
+ }
43
+ }