forgehive 0.7.1 → 0.7.2

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 (3) hide show
  1. package/README.md +262 -33
  2. package/dist/cli.js +90 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -14,8 +14,8 @@
14
14
  <p align="center">
15
15
  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js ≥ 18">
16
16
  <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
17
- <img src="https://img.shields.io/badge/tests-217%20passing-success" alt="217 tests">
18
- <img src="https://img.shields.io/badge/bundle-205KB-lightgrey" alt="205KB bundle">
17
+ <img src="https://img.shields.io/badge/tests-267%20passing-success" alt="267 tests">
18
+ <img src="https://img.shields.io/badge/bundle-244KB-lightgrey" alt="244KB bundle">
19
19
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
20
20
  </p>
21
21
 
@@ -31,18 +31,23 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
31
31
 
32
32
  - **Stack Scanner** — detects tech stack, dependencies, and project structure automatically
33
33
  - **Persistent Memory** — context and session notes survive every restart
34
+ - **Story & Epic Tracking** — lightweight agile backlog inside `.forgehive/memory/`
35
+ - **Velocity Tracking** — sprint velocity history, rolling average, and capacity hints
34
36
  - **Party Mode** — specialized agent sets, each agent in its own isolated git worktree
35
37
  - **MCP Wiring** — preconfigured connectors for 10 services, API keys stored securely in `~/.forgehive/`
36
38
  - **Security Suite** — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
39
+ - **CI Integration** — CI health report and GitHub Actions template generator
40
+ - **Codebase Map** — file/line/import table for navigation and onboarding
41
+ - **Team Sync** — share memory across the team via a dedicated git branch
37
42
  - **AGENTS.md** — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)
38
43
 
39
44
  **Design principle:** writes exclusively to `.forgehive/` in the target project. No globbing outside the project root. Never overwrites files it didn't create.
40
45
 
41
46
  ---
42
47
 
43
- ## Status: Early Alpha (v0.6)
48
+ ## Status: v0.7 Stable
44
49
 
45
- This is an early release. The codebase is clean — TypeScript, 217 passing tests, single bundle but several features have not yet been tested against a real project.
50
+ 267 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
46
51
 
47
52
  **Stable — use with confidence:**
48
53
 
@@ -56,6 +61,16 @@ This is an early release. The codebase is clean — TypeScript, 217 passing test
56
61
  | `fh security report` — compliance reports | stable |
57
62
  | `fh memory` — show, clean, export, snapshot | stable |
58
63
  | MCP credential store (`fh mcp auth`) | stable |
64
+ | `fh ci` — CI health report + GitHub Actions template | stable |
65
+ | `fh map` — codebase structure map | stable |
66
+ | `fh onboard` — generates ONBOARDING.md | stable |
67
+ | `fh changelog` — semantic changelog from git | stable |
68
+ | `fh metrics` — developer metrics by author/type | stable |
69
+ | `fh sync` — team memory sharing via git branch | stable |
70
+ | `fh run` — background agent execution via `claude -p` | stable |
71
+ | `fh story` — story card create/list/show/done | stable |
72
+ | `fh epic` — epic create/list/show | stable |
73
+ | `fh velocity` — show history + record sprint data | stable |
59
74
 
60
75
  **Experimental — works in tests, not yet live-validated:**
61
76
 
@@ -74,7 +89,7 @@ If you run into issues, please open an issue on GitHub. The most valuable feedba
74
89
 
75
90
  - **Node.js ≥ 18** — check with `node --version`
76
91
  - **Claude Code** installed and configured (`claude` CLI available)
77
- - **git** — required for Party Mode worktrees and the guardrails hook
92
+ - **git** — required for Party Mode worktrees, `fh sync`, and the guardrails hook
78
93
 
79
94
  ---
80
95
 
@@ -94,14 +109,14 @@ This makes both `fh` and `forgehive` available globally.
94
109
  git clone https://github.com/matharnica/forgehive
95
110
  cd forgehive
96
111
  npm install
97
- npm run build # compiles to dist/cli.js (~205 KB)
112
+ npm run build # compiles to dist/cli.js (~244 KB)
98
113
  npm link # makes 'fh' available globally
99
114
  ```
100
115
 
101
116
  Verify the installation:
102
117
 
103
118
  ```bash
104
- fh --version # should print 0.6.0
119
+ fh --version # should print 0.7.1
105
120
  fh --help # lists all available commands
106
121
  ```
107
122
 
@@ -264,6 +279,91 @@ Shows `permissions.yaml` — the file access control list for each agent. Each a
264
279
 
265
280
  ---
266
281
 
282
+ ### CI
283
+
284
+ ```bash
285
+ fh ci # run CI health report (text output)
286
+ fh ci --format json # output report as JSON
287
+ fh ci --format markdown # output report as Markdown
288
+ fh ci --fail-on critical # exit 1 only on CRITICAL findings
289
+ fh ci --fail-on high # exit 1 on HIGH or CRITICAL
290
+ fh ci --fail-on any # exit 1 on any finding
291
+ fh ci --init # generate a GitHub Actions workflow template
292
+ ```
293
+
294
+ `fh ci` aggregates security scan, dependency audit, and test results into a single CI health report. Use `--init` to scaffold a `.github/workflows/forgehive.yml` file that runs the full check on every pull request. The `--fail-on` flag controls which severity level causes a non-zero exit code, giving you fine-grained control over what blocks a merge.
295
+
296
+ ---
297
+
298
+ ### Codebase Map
299
+
300
+ ```bash
301
+ fh map
302
+ ```
303
+
304
+ Prints a structured table of your codebase: file paths, line counts, and import relationships. Useful for onboarding a new engineer (or a new Claude session) to an unfamiliar codebase. Output goes to stdout; pipe it to a file if you want to save it.
305
+
306
+ ---
307
+
308
+ ### Onboarding
309
+
310
+ ```bash
311
+ fh onboard # generate ONBOARDING.md (stdout)
312
+ fh onboard --output ./ONBOARDING.md # write to file
313
+ ```
314
+
315
+ Generates a human-readable `ONBOARDING.md` from three sources: the detected stack in `capabilities.yaml`, the persistent memory in `.forgehive/memory/`, and the recent git log. The result is a self-contained document a new team member can read to understand the project architecture, conventions, and current state.
316
+
317
+ ---
318
+
319
+ ### Changelog
320
+
321
+ ```bash
322
+ fh changelog # full changelog from all commits
323
+ fh changelog --since v0.6.0 # changes since a specific tag
324
+ fh changelog --output CHANGELOG.md # write to file
325
+ ```
326
+
327
+ Parses conventional commits (`feat:`, `fix:`, `chore:`, `docs:`, etc.) and groups them into a semantic changelog. Breaking changes are surfaced separately. Requires conventional commit messages — standard for projects that use `fh git-conventions`.
328
+
329
+ ---
330
+
331
+ ### Developer Metrics
332
+
333
+ ```bash
334
+ fh metrics # all-time developer metrics
335
+ fh metrics --since 2025-01-01 # metrics since a date
336
+ ```
337
+
338
+ Shows commit activity broken down by author and commit type (feat, fix, chore, docs, test, refactor). Also shows rolling statistics: commit frequency, most active contributors, and type distribution. Useful for retrospectives and identifying contribution patterns.
339
+
340
+ ---
341
+
342
+ ### Team Memory Sync
343
+
344
+ ```bash
345
+ fh sync push # push memory to default remote/branch
346
+ fh sync push --remote origin --branch forgehive-memory # push to a specific remote branch
347
+ fh sync pull # pull memory from remote
348
+ fh sync pull --remote origin --branch forgehive-memory # pull from specific branch
349
+ ```
350
+
351
+ `fh sync` shares `.forgehive/memory/` across the team by pushing to (or pulling from) a dedicated git branch. This is an alternative to committing the memory directory into the main branch. On `pull`, existing local files are not overwritten — only new files are added, the same idempotent behavior as `fh memory snapshot import`.
352
+
353
+ ---
354
+
355
+ ### Background Agent Execution
356
+
357
+ ```bash
358
+ fh run <issue-url> # run agent on a GitHub/Linear issue URL
359
+ fh run <issue-url> --agent kai # use a specific agent
360
+ fh run <issue-url> --label ready-for-ai # filter by label
361
+ ```
362
+
363
+ `fh run` launches a background agent via `claude -p`, passes the issue content as context, and returns immediately. The agent reads the issue, applies forgehive context from `.forgehive/`, and works on the task in the background. Useful for automating repetitive issues or running agents overnight. Agent output is streamed to stdout and also written to `.forgehive/runs/`.
364
+
365
+ ---
366
+
267
367
  ### Memory
268
368
 
269
369
  Memory files live in `.forgehive/memory/` and are read by Claude at session start via the CLAUDE.md block.
@@ -297,6 +397,55 @@ Memory files live in `.forgehive/memory/` and are read by Claude at session star
297
397
 
298
398
  ---
299
399
 
400
+ ### Story Cards
401
+
402
+ Story cards are lightweight user stories stored in `.forgehive/memory/stories/`. They integrate with `/fh-sprint` for velocity-based sprint planning.
403
+
404
+ ```bash
405
+ fh story create "As a user I want to log in" # create a story (auto-numbered US-N)
406
+ fh story create "As a user I want to log in" --epic EPC-1 --points 3 # with epic + points
407
+ fh story list # list all backlog stories
408
+ fh story list --epic EPC-1 # filter by epic
409
+ fh story show US-1 # show full story card with acceptance criteria
410
+ fh story done US-1 # mark story as done
411
+ fh story done US-1 --points 5 # mark done and record actual points
412
+ ```
413
+
414
+ Each story card is a Markdown file at `.forgehive/memory/stories/US-N.md`. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (`backlog` | `done`). When you run `/fh-sprint` in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.
415
+
416
+ ---
417
+
418
+ ### Epics
419
+
420
+ Epics group related stories and are stored in `.forgehive/memory/epics/`.
421
+
422
+ ```bash
423
+ fh epic create "User Authentication" # create an epic (auto-numbered EPC-N)
424
+ fh epic create "User Authentication" --goal "Users can log in securely" # with a goal statement
425
+ fh epic list # list all epics
426
+ fh epic show EPC-1 # show epic with linked stories and point total
427
+ ```
428
+
429
+ Each epic card is a Markdown file at `.forgehive/memory/epics/EPC-N.md`. `fh epic show` aggregates all stories linked to the epic and displays their status and point totals.
430
+
431
+ ---
432
+
433
+ ### Velocity
434
+
435
+ ```bash
436
+ fh velocity show # velocity history + rolling average + recommendation
437
+ fh velocity record sprint-3 --committed 21 --delivered 18 # record sprint data
438
+ ```
439
+
440
+ `fh velocity show` reads the velocity history from `.forgehive/memory/velocity.md` and prints:
441
+ - A table of past sprints (committed vs. delivered points)
442
+ - A rolling average (last 3 sprints)
443
+ - A capacity recommendation for the next sprint
444
+
445
+ `fh velocity record` appends a new entry to the velocity history. The `/fh-sprint` slash command reads this data automatically and uses it to calibrate the sprint scope it suggests.
446
+
447
+ ---
448
+
300
449
  ### Party Mode
301
450
 
302
451
  Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.
@@ -320,7 +469,7 @@ fh party cleanup # remove finished worktrees
320
469
  | `security` | Vera + Sam | `/security-party` |
321
470
  | `full` | All 8 agents | `/full-party` |
322
471
 
323
- **Model mapping** — assign specific Claude models per agent:
472
+ **Multi-model routing** — `defaults.yaml` supports a `models:` key per agent set. Override via CLI:
324
473
 
325
474
  ```bash
326
475
  fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"
@@ -417,33 +566,57 @@ Clones the repo with `--depth=1`, copies all `.md` files from the `skills/expert
417
566
 
418
567
  ---
419
568
 
569
+ ### Slash Commands
570
+
571
+ The following slash commands are available inside Claude Code sessions:
572
+
573
+ | Command | Description |
574
+ |---|---|
575
+ | `/fh-sprint` | Sprint planning — reads backlog, velocity, and capacity; suggests scope using Fibonacci points (1/2/3/5/8/13); records velocity at end of sprint |
576
+ | `/fh-deploy` | Pre-deploy checklist — security scan, dependency audit, test run, final confirmation |
577
+ | `/fh-test-this` | Generate tests for the current file or selection — uses `testing-strategies` skill |
578
+ | `/fh-docs` | Generate documentation for the current file or module |
579
+ | `/party` | Start the `build` party (Viktor + Kai + Sam) |
580
+ | `/design-party` | Start the `design` party (Suki + Viktor) |
581
+ | `/review-party` | Start the `review` party (Kai + Sam + Eli) |
582
+ | `/security-party` | Start the `security` party (Vera + Sam) |
583
+ | `/full-party` | Start all 8 agents |
584
+
585
+ **`/fh-sprint` in detail:** Reads `.forgehive/memory/stories/` for backlog items, `.forgehive/memory/velocity.md` for historical capacity, and `.forgehive/memory/epics/` for epic context. Suggests a sprint scope as a list of story cards with Fibonacci point estimates. When you close the sprint, it prompts you to record delivered points so velocity history stays up to date. If Linear or GitHub MCP servers are connected, it can pull issues directly from those services.
586
+
587
+ ---
588
+
420
589
  ## What `fh init` Creates
421
590
 
422
591
  ```
423
592
  my-project/
424
593
  .forgehive/
425
- capabilities.yaml detected stack (status: draft confirmed)
426
- scan-result.yaml raw scanner output
427
- .scan-hash checksum for fh scan --check
594
+ capabilities.yaml <- detected stack (status: draft -> confirmed)
595
+ scan-result.yaml <- raw scanner output
596
+ .scan-hash <- checksum for fh scan --check
428
597
  harness/
429
- architecture.md codebase overview for Claude
430
- constraints.yaml max_lines, require_tests, style rules
431
- permissions.yaml per-agent file access control (read/write/deny)
598
+ architecture.md <- codebase overview for Claude
599
+ constraints.yaml <- max_lines, require_tests, style rules
600
+ permissions.yaml <- per-agent file access control (read/write/deny)
432
601
  memory/
433
- MEMORY.md index of all memory files
434
- project.md project context and open decisions
435
- feedback.md corrections + confirmed approaches
436
- stack.md stack details the scanner can't detect
437
- adrs/ architecture decision records
602
+ MEMORY.md <- index of all memory files
603
+ project.md <- project context and open decisions
604
+ feedback.md <- corrections + confirmed approaches
605
+ stack.md <- stack details the scanner can't detect
606
+ adrs/ <- architecture decision records
607
+ stories/ <- story cards (US-N.md)
608
+ epics/ <- epic cards (EPC-N.md)
609
+ velocity.md <- sprint velocity history
438
610
  skills/
439
- generated/ AI-generated skills (fh skills regen)
440
- expert/ 16 preinstalled expert skills
441
- workflows/ MCP workflow skills
442
- worktrees/ isolated git worktrees (fh party run)
443
- audit.log ← JSONL audit trail (fh security commands)
444
- cost-config.yaml ← spend limits (fh cost --limit/--alert)
445
- AGENTS.md ← cross-tool agent standard
446
- CLAUDE.md forgehive block inserted, rest preserved
611
+ generated/ <- AI-generated skills (fh skills regen)
612
+ expert/ <- 16 preinstalled expert skills
613
+ workflows/ <- MCP workflow skills
614
+ worktrees/ <- isolated git worktrees (fh party run)
615
+ runs/ <- background agent output (fh run)
616
+ audit.log <- JSONL audit trail (fh security commands)
617
+ cost-config.yaml <- spend limits (fh cost --limit/--alert)
618
+ AGENTS.md <- cross-tool agent standard
619
+ CLAUDE.md <- forgehive block inserted, rest preserved
447
620
  ```
448
621
 
449
622
  ---
@@ -520,7 +693,7 @@ The hook fires on every bash command execution in Claude Code and exits 1 if a m
520
693
  cd my-project
521
694
  fh init
522
695
  fh confirm
523
- # Open Claude Code Claude now has full context
696
+ # Open Claude Code -> Claude now has full context
524
697
  ```
525
698
 
526
699
  ### After adding new dependencies
@@ -539,6 +712,49 @@ fh security deps # check for new CVEs in dependencies
539
712
  fh security report gdpr # update compliance report
540
713
  ```
541
714
 
715
+ ### CI integration
716
+
717
+ ```bash
718
+ fh ci --init # scaffold .github/workflows/forgehive.yml
719
+ fh ci --format markdown --fail-on high # use in existing CI scripts
720
+ ```
721
+
722
+ ### Generating onboarding documentation
723
+
724
+ ```bash
725
+ fh map # review codebase structure
726
+ fh onboard --output ONBOARDING.md # generate onboarding document
727
+ git add ONBOARDING.md
728
+ git commit -m "docs: add forgehive-generated onboarding"
729
+ ```
730
+
731
+ ### Generating a changelog
732
+
733
+ ```bash
734
+ fh changelog --since v0.6.0 --output CHANGELOG.md
735
+ ```
736
+
737
+ ### Sprint planning
738
+
739
+ ```bash
740
+ # Set up your backlog
741
+ fh epic create "User Authentication" --goal "Users can log in securely"
742
+ fh story create "As a user I want to log in" --epic EPC-1 --points 3
743
+ fh story create "As a user I want to reset my password" --epic EPC-1 --points 2
744
+
745
+ # Check current velocity
746
+ fh velocity show
747
+
748
+ # Open Claude Code and run:
749
+ # /fh-sprint
750
+ # Claude reads velocity + backlog and suggests scope
751
+
752
+ # At end of sprint
753
+ fh velocity record sprint-1 --committed 13 --delivered 11
754
+ fh story done US-1
755
+ fh story done US-2
756
+ ```
757
+
542
758
  ### Sharing context with the team
543
759
 
544
760
  ```bash
@@ -548,6 +764,11 @@ git commit -m "chore: update shared forgehive context"
548
764
 
549
765
  # On another machine:
550
766
  fh memory snapshot import ./team-context.json
767
+
768
+ # Or use the sync approach (no committed file):
769
+ fh sync push --remote origin --branch forgehive-memory
770
+ # teammate runs:
771
+ fh sync pull --remote origin --branch forgehive-memory
551
772
  ```
552
773
 
553
774
  ### Starting a multi-agent build session
@@ -555,8 +776,8 @@ fh memory snapshot import ./team-context.json
555
776
  ```bash
556
777
  fh party --set build
557
778
  fh party run
558
- # Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
559
- # Each Claude Code session opens in its own isolated worktree
779
+ # -> Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
780
+ # -> Each Claude Code session opens in its own isolated worktree
560
781
 
561
782
  fh party status # check what's running
562
783
  fh party cleanup # clean up after the session
@@ -575,6 +796,14 @@ fh mcp auth add github GITHUB_TOKEN=ghp_...
575
796
  fh mcp auth list # verify both services are stored
576
797
  ```
577
798
 
799
+ ### Running a background agent on an issue
800
+
801
+ ```bash
802
+ fh run https://github.com/my-org/my-repo/issues/42 --agent kai
803
+ # Kai reads the issue, applies forgehive context, works in background
804
+ # Output streamed to stdout and saved to .forgehive/runs/
805
+ ```
806
+
578
807
  ---
579
808
 
580
809
  ## Configuration Files
@@ -613,13 +842,13 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
613
842
  |---|---|
614
843
  | Runtime | Node.js ≥ 18, ESM |
615
844
  | Language | TypeScript |
616
- | Build | esbuild `dist/cli.js` (~205 KB, single bundle) |
845
+ | Build | esbuild -> `dist/cli.js` (~244 KB, single bundle) |
617
846
  | Type check | `tsc --noEmit` |
618
- | Tests | `node:test` (native) + tsx ESM loader, 217 tests |
847
+ | Tests | `node:test` (native) + tsx ESM loader, 267 tests |
619
848
  | Dependencies | `js-yaml` (sole runtime dependency) |
620
849
 
621
850
  ```bash
622
- npm run build # esbuild dist/cli.js
851
+ npm run build # esbuild -> dist/cli.js
623
852
  npm run typecheck # tsc --noEmit
624
853
  npm test # node --import tsx/esm --test test/*.test.ts
625
854
  ```
package/dist/cli.js CHANGED
@@ -6459,7 +6459,75 @@ var [, , command, subcommand, ...rest] = process.argv;
6459
6459
  var projectRoot = process.cwd();
6460
6460
  var forgehiveDir = path31.join(projectRoot, ".forgehive");
6461
6461
  if (command === "--version" || command === "-v") {
6462
- console.log("0.7.1");
6462
+ console.log("0.7.2");
6463
+ process.exit(0);
6464
+ }
6465
+ if (command === "--help" || command === "-h" || command === "help") {
6466
+ console.log(`
6467
+ forgehive v0.7.2 \u2014 Context-aware AI development environment
6468
+
6469
+ USAGE
6470
+ fh <command> [subcommand] [options]
6471
+
6472
+ SETUP
6473
+ fh init Set up forgehive in the current project
6474
+ fh confirm Activate capabilities (draft \u2192 confirmed)
6475
+ fh rollback Remove forgehive from the project
6476
+ fh status Show current project state
6477
+ fh scan --update Re-scan project after changes
6478
+ fh scan --check Check if scan is still current
6479
+
6480
+ SECURITY
6481
+ fh security scan Secrets + SAST scan
6482
+ fh security deps CVE check (npm audit)
6483
+ fh security report [gdpr|soc2|hipaa] Compliance report
6484
+ fh security audit Show audit trail
6485
+ fh security permissions Show agent file permissions
6486
+
6487
+ CI
6488
+ fh ci Run CI health report
6489
+ fh ci --format json|markdown Output format
6490
+ fh ci --fail-on critical|high|any Failure threshold
6491
+ fh ci --init Generate GitHub Actions workflow
6492
+
6493
+ CODEBASE
6494
+ fh map Codebase structure map
6495
+ fh onboard [--output path] Generate ONBOARDING.md
6496
+ fh changelog [--since tag] Semantic changelog from git
6497
+ fh metrics [--since date] Developer productivity metrics
6498
+
6499
+ SPRINT PLANNING
6500
+ fh story create <title> [--epic EPC-N] [--points N]
6501
+ fh story list [--epic EPC-N]
6502
+ fh story show <US-N>
6503
+ fh story sprint <US-N> Mark story as in-sprint
6504
+ fh story done <US-N> [--points N]
6505
+ fh epic create <title> [--goal <text>]
6506
+ fh epic list
6507
+ fh epic show <EPC-N>
6508
+ fh velocity show Velocity history + rolling average
6509
+ fh velocity record <N> --committed N --delivered N
6510
+
6511
+ TEAM
6512
+ fh sync push|pull [--remote origin --branch forgehive-memory]
6513
+ fh run <issue-url> [--agent name] [--label label]
6514
+ fh memory show|clean|export|prune|snapshot
6515
+ fh memory adr list|"<title>"
6516
+
6517
+ AGENTS & MCP
6518
+ fh party [--set name|run|status|cleanup]
6519
+ fh wire <service> Configure MCP server
6520
+ fh mcp auth add|list|remove Manage credentials
6521
+ fh mcp search <query> Search MCP registry
6522
+ fh skills list|regen|pull <url>
6523
+
6524
+ COST
6525
+ fh cost [today|week|all]
6526
+ fh cost --limit N --alert N
6527
+
6528
+ fh --version Show version
6529
+ fh --help Show this help
6530
+ `);
6463
6531
  process.exit(0);
6464
6532
  }
6465
6533
  function loadClaudeMdBlock() {
@@ -6474,6 +6542,13 @@ function loadClaudeMdBlock() {
6474
6542
  return fs30.readFileSync(templatePath, "utf8");
6475
6543
  }
6476
6544
  if (command === "init") {
6545
+ const forgehiveDirExists = fs30.existsSync(forgehiveDir);
6546
+ if (forgehiveDirExists && !rest.includes("--force")) {
6547
+ console.log(`\u26A0 .forgehive/ existiert bereits in diesem Projekt.`);
6548
+ console.log(` Nutze 'fh init --force' um neu zu initialisieren (\xFCberschreibt capabilities.yaml).`);
6549
+ console.log(` Nutze 'fh scan --update' um nur den Scan zu aktualisieren.`);
6550
+ process.exit(0);
6551
+ }
6477
6552
  console.log("\u{1F50D} Analysiere Projekt...\n");
6478
6553
  const scanResult = scan(projectRoot);
6479
6554
  const tierCount = [1, 2, 3].map((t) => scanResult.signals.filter((s) => s.tier === t).length);
@@ -7264,6 +7339,14 @@ Setze diese Umgebungsvariablen:`);
7264
7339
  if (pointsArg) updateStoryPoints(storiesDir, id, pointsArg);
7265
7340
  updateStoryStatus(storiesDir, id, "done");
7266
7341
  console.log(`\u2714 ${id} als done markiert`);
7342
+ } else if (subcommand === "sprint") {
7343
+ const id = rest[0];
7344
+ if (!id) {
7345
+ console.error("Usage: fh story sprint <US-N>");
7346
+ process.exit(1);
7347
+ }
7348
+ updateStoryStatus(storiesDir, id, "in-sprint");
7349
+ console.log(`\u2714 ${id} in Sprint gezogen`);
7267
7350
  } else if (subcommand === "show") {
7268
7351
  const id = rest[0];
7269
7352
  if (!id) {
@@ -7328,14 +7411,16 @@ Setze diese Umgebungsvariablen:`);
7328
7411
  recordVelocity(velocityFile, sprintNum, committed, delivered);
7329
7412
  const avg = getRollingAverage(getVelocityHistory(velocityFile));
7330
7413
  console.log(`\u2714 Sprint ${sprintNum} gespeichert. Rolling Average: ${avg} Punkte`);
7331
- } else {
7414
+ } else if (!subcommand || subcommand === "show") {
7332
7415
  const history = getVelocityHistory(velocityFile);
7333
7416
  console.log(formatVelocityReport(history));
7417
+ } else {
7418
+ console.error("Verf\xFCgbar: fh velocity show | record <N> --committed N --delivered N");
7334
7419
  }
7335
7420
  } else {
7336
- const cmd = [command, subcommand].filter(Boolean).join(" ") || "(kein)";
7337
- console.error(`Unbekannter Befehl: ${cmd}`);
7338
- console.error("Verf\xFCgbar: init | confirm | rollback | scan --update | scan --check | status | ci [--format json|markdown] [--fail-on critical|high|any] [--init] | map | onboard [--output path] | changelog [--since tag] | metrics [--since date] | sync [push|pull] [--remote origin --branch forgehive-memory] | run <issue-url> [--agent <name>] | cost [today|week|all] | cost --limit N --alert N | memory [show|clean|export|prune|snapshot] | memory adr [list|<titel>] | skills [list|regen|pull <url>] | party [--set <name>|run|status|cleanup] | wire <service> | mcp [auth|search|add] | security [scan|deps|report|audit|permissions]");
7421
+ console.error("Unbekannter Befehl: " + command);
7422
+ console.error("Verf\xFCgbar: init | confirm | rollback | scan | status | ci | map | onboard | changelog | metrics | story [create|list|show|sprint|done] | epic [create|list|show] | velocity [show|record] | sync [push|pull] | run <issue-url> | cost | memory | skills | party | wire | mcp | security");
7423
+ console.error("Hilfe: fh --help");
7339
7424
  process.exit(1);
7340
7425
  }
7341
7426
  /*! Bundled license information:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forgehive",
3
- "version": "0.7.1",
3
+ "version": "0.7.2",
4
4
  "description": "Context-aware AI development environment — one binary, your stack.",
5
5
  "type": "module",
6
6
  "bin": {