forgehive 0.7.9 → 0.8.1

package/docs/user-guide.md

@@ -1,6 +1,6 @@
 # forgehive — User Guide
 
-> Version 0.7.7 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
+> Version 0.8.0 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
 
 forgehive (`fh`) gives Claude Code persistent memory about your project. Without it, Claude forgets everything between sessions — your stack, your conventions, your decisions. With it, Claude opens every session already knowing your codebase.
 
@@ -17,7 +17,7 @@ Requires **Node.js ≥ 18** and **Claude Code** (`claude` CLI). Installs two ali
 Verify:
 
 ```bash
-fh --version   # prints 0.7.7
+fh --version   # prints 0.8.0
 fh --help      # full command reference
 ```
 
@@ -63,6 +63,7 @@ my-project/
       adrs/               ← Architecture Decision Records
       stories/            ← story cards (US-N.md)
       epics/              ← epic cards (EPC-N.md)
+      prds/               ← Product Requirements Documents (PRD-N.md)
       velocity.md         ← sprint velocity history
     skills/expert/        ← 16 preinstalled expert skills
   AGENTS.md
@@ -196,6 +197,7 @@ Lightweight agile tracking inside `.forgehive/memory/`:
 ```bash
 # Epics
 fh epic create "User Authentication" --goal "Users can log in securely"
+fh epic create "User Authentication" --prd PRD-1   # link to a PRD
 fh epic list
 fh epic show EPC-1
 
@@ -216,6 +218,83 @@ In a Claude Code session, run `/fh-sprint` to let Claude read the backlog and ve
 
 ---
 
+### GitHub Integration
+
+Connect forgehive to GitHub to sync Issues as Story cards and pull PR context.
+
+```bash
+fh github setup         # interactive: GitHub token + owner/repo → stored in ~/.forgehive/credentials.json
+fh github sync          # fetch open Issues → create Story cards (idempotent, skips already-synced)
+fh github pr 42         # fetch PR #42 metadata + changed files → .forgehive/github-pr-42.md
+```
+
+**Setup is a one-time step.** `fh github setup` prompts for a personal access token (stored at `~/.forgehive/credentials.json`) and the repository in `owner/repo` format (stored at `.forgehive/github.yaml`).
+
+**Issue sync** creates one Story card per open GitHub Issue. It's idempotent — run it multiple times without duplicating cards. Already-synced issues (detected by `GitHub: #N` in the story file) are skipped.
+
+**PR context** writes a `.forgehive/github-pr-N.md` file with the PR title, body, author, and full list of changed files — useful to share with a Review Party:
+
+```bash
+fh github pr 42
+fh party run review    # Kai + Sam + Eli each read the PR context
+```
+
+---
+
+### Intelligent Routing — fh ask
+
+Not sure which agent to use? Describe the task:
+
+```bash
+fh ask "fix the login timeout bug"
+fh ask "write integration tests for the payment service"
+fh ask "design the new onboarding flow"
+fh ask "review the auth module for security issues"
+```
+
+`fh ask` analyzes the task description using keyword matching and returns:
+- **Which agent or party** to use
+- **Confidence level** (high / medium / low)
+- **Why** — which keywords triggered the recommendation
+- **Exact command** to run — either `cd <worktree> && claude` for a single agent or `fh party run <set>` for a party
+
+`fh run "<freetext>"` does the same when the argument isn't a URL:
+
+```bash
+fh run "refactor the database layer"   # routes to best agent automatically
+```
+
+---
+
+### Product Workflow
+
+`fh product` manages the full PRD → Epic → Story pipeline.
+
+```bash
+# PRDs
+fh product prd "User Authentication Redesign"   # create PRD-N (auto-incremented)
+fh product list                                  # list all PRDs with status and date
+fh product show PRD-1                            # print full PRD content
+
+# Pipeline view
+fh product status                                # tree: PRDs → Epics → Stories with status
+fh product roadmap                               # write ROADMAP.md to project root
+```
+
+**Typical flow:**
+
+```bash
+fh product prd "Onboarding Redesign"
+fh epic create "Welcome Flow" --prd PRD-1 --goal "Users complete setup in < 5 min"
+fh story create "As a new user I want to see a setup checklist" --epic EPC-1 --points 3
+fh product status    # see the full pipeline as a tree
+fh product roadmap   # generate ROADMAP.md
+```
+
+`fh epic create --prd PRD-N` links the epic to a PRD at creation time. Epics without a PRD link appear as orphans in `fh product status`.
+
+---
+
 ## Party Mode — Parallel Agent Sessions
 
 Party Mode runs specialized agent sets in parallel, each in an isolated git worktree. Use this for reviews, design sessions, or full-release audits.
@@ -340,3 +419,9 @@ Run `fh party cleanup` to remove all finished worktrees.
 
 **`fh cost` shows no data**
 Cost tracking reads `~/.claude/` — requires Claude Code to be installed and to have run at least one session.
+
+**`fh github sync` creates duplicate stories**
+This shouldn't happen — `fh github sync` checks for `GitHub: #N` in existing story files and skips them. If you see duplicates, check that the story file contains the `GitHub: #N` reference line.
+
+**`fh github setup` says "Nicht konfiguriert"**
+Run `fh github setup` to configure the token and repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.9",
+  "version": "0.8.1",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {