forgehive 0.7.9 → 0.8.0

package/README.md

@@ -14,8 +14,8 @@
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js ≥ 18">
   <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
-  <img src="https://img.shields.io/badge/tests-273%20passing-success" alt="273 tests">
-  <img src="https://img.shields.io/badge/bundle-259KB-lightgrey" alt="259KB bundle">
+  <img src="https://img.shields.io/badge/tests-369%20passing-success" alt="369 tests">
+  <img src="https://img.shields.io/badge/bundle-293KB-lightgrey" alt="293KB bundle">
   <img src="https://img.shields.io/badge/license-Elastic%202.0-orange" alt="Elastic License 2.0">
 </p>
 
@@ -37,7 +37,10 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 - **MCP Wiring** — preconfigured connectors for 10 services, API keys stored securely in `~/.forgehive/`
 - **Security Suite** — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
 - **CI Integration** — CI health report and GitHub Actions template generator
-- **Codebase Map** — file/line/import table for navigation and onboarding
+- **Codebase Map** — file/line/import table + semantic graph (hotspots, cycles, dependency stats)
+- **GitHub Integration** — sync open Issues as Stories, fetch PR context, interactive token setup
+- **Intelligent Routing** — `fh ask "<task>"` recommends the right agent or party set with a start command
+- **Product Workflow** — PRD → Epic → Story pipeline with roadmap generation
 - **Team Sync** — share memory across the team via a dedicated git branch
 - **AGENTS.md** — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)
 
@@ -45,9 +48,9 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 ---
 
-## Status: v0.7.7 — Stable
+## Status: v0.8.0 — Stable
 
-297 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
+369 passing tests back the commands listed below. The v0.8 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -62,7 +65,17 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 | `fh memory` — show, clean, export, snapshot | stable |
 | MCP credential store (`fh mcp auth`) | stable |
 | `fh ci` — CI health report + GitHub Actions template | stable |
-| `fh map` — codebase structure map | stable |
+| `fh map` — codebase structure map + semantic graph | stable |
+| `fh map --semantic` — semantic graph only (hotspots, cycles) | stable |
+| `fh github setup` — interactive token + repo configuration | stable |
+| `fh github sync` — sync open GitHub Issues as Story cards | stable |
+| `fh github pr <N>` — fetch PR metadata + changed files | stable |
+| `fh ask "<task>"` — intelligent agent/party routing | stable |
+| `fh run <freetext>` — route freetext tasks to best agent | stable |
+| `fh product prd` — create/list/show PRDs | stable |
+| `fh product status` — PRD → Epic → Story pipeline tree | stable |
+| `fh product roadmap` — generate ROADMAP.md | stable |
+| `fh epic create --prd PRD-N` — link epic to a PRD | stable |
 | `fh onboard` — generates ONBOARDING.md | stable |
 | `fh changelog` — semantic changelog from git | stable |
 | `fh metrics` — developer metrics by author/type | stable |
@@ -125,7 +138,7 @@ npm link           # makes 'fh' available globally
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.7.7
+fh --version       # should print 0.8.0
 fh --help          # lists all available commands
 ```
 
@@ -311,10 +324,18 @@ fh ci --init                   # generate a GitHub Actions workflow template
 ### Codebase Map
 
 ```bash
-fh map
+fh map                  # full map + semantic graph (written to map.md)
+fh map --semantic       # print only the semantic graph to stdout
 ```
 
-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.
+`fh map` writes a structured table of your codebase — file paths, line counts, and import relationships — to `map.md`. It also runs a full semantic analysis and appends a `## Semantic Graph` section to the file.
+
+The **semantic graph** shows:
+- **Hotspots** — files imported by 3+ others (sorted by import count), indicating high-impact modules
+- **Cycles** — circular dependency chains detected via DFS
+- **Dependency summary** — total files, edges, and average fanout
+
+`fh map --semantic` prints only the `## Semantic Graph` block to stdout — useful for piping directly into a Claude session as focused context.
 
 ---
 
@@ -388,10 +409,45 @@ fh sync pull --remote origin --branch forgehive-memory  # pull from specific bra
 fh run <issue-url>                         # run agent on a GitHub/Linear issue URL
 fh run <issue-url> --agent kai             # use a specific agent
 fh run <issue-url> --label ready-for-ai   # filter by label
+fh run "fix the login bug in auth.ts"      # freetext → routed to best agent automatically
 ```
 
 `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/`.
 
+When the argument is not a URL, `fh run` delegates to the same routing logic as `fh ask` and recommends the right agent or party set with a concrete start command.
+
+---
+
+### Intelligent Routing
+
+```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` analyzes the task description and recommends the right agent or party set. It returns:
+- **Which agent or party** to use (with confidence level: high / medium / low)
+- **Why** — which keywords triggered the match
+- **Exact command** to start — either `cd <worktree> && claude` for a single agent or `fh party run <set>` for a party
+
+**Routing table:**
+
+| Keywords | Routes to |
+|---|---|
+| security, vulnerability, auth, OWASP | Vera (security analyst) |
+| test, coverage, spec, assertion | Sam (QA architect) |
+| design, UI, UX, figma, wireframe | Suki (UX designer) |
+| architecture, scalability, refactor structure | Viktor (system architect) |
+| docs, README, onboarding, tutorial | Eli (documentation) |
+| research, compare, analyze, investigate | Nora (research analyst) |
+| product, roadmap, PRD, user story | Remy (product strategist) |
+| bug, fix, crash, error, regression | Kai (senior engineer) |
+| 3+ domains | `full` party |
+| security + review | `security` party |
+| architecture + QA | `refactor` party |
+| architecture + engineering | `build` party |
+
 ---
 
 ### Memory
@@ -453,6 +509,7 @@ Epics group related stories and are stored in `.forgehive/memory/epics/`.
 ```bash
 fh epic create "User Authentication"                              # create an epic (auto-numbered EPC-N)
 fh epic create "User Authentication" --goal "Users can log in securely"  # with a goal statement
+fh epic create "User Authentication" --prd PRD-1                  # link to a PRD at creation time
 fh epic list                                                       # list all epics
 fh epic show EPC-1                                                 # show epic with linked stories and point total
 ```
@@ -461,6 +518,76 @@ Each epic card is a Markdown file at `.forgehive/memory/epics/EPC-N.md`. `fh epi
 
 ---
 
+### Product Workflow
+
+`fh product` manages the full **PRD → Epic → Story** pipeline.
+
+#### PRDs (Product Requirements Documents)
+
+```bash
+fh product prd "User Authentication"       # create PRD-N (auto-incremented)
+fh product list                            # list all PRDs with status and date
+fh product show PRD-1                      # print full PRD content
+```
+
+PRDs are stored in `.forgehive/memory/prds/` as `YYYY-MM-DD-<slug>.md` with a standard template (Overview, Goals, Non-Goals, User Stories, Success Metrics, Open Questions).
+
+#### Pipeline Overview
+
+```bash
+fh product status                          # tree view: PRDs → Epics → Stories
+fh product roadmap                         # generate ROADMAP.md from all PRDs + Epics + Stories
+```
+
+`fh product status` prints a tree of all PRDs, linked epics, and their stories with status indicators. Epics without a PRD are shown at the bottom as orphans.
+
+`fh product roadmap` writes a `ROADMAP.md` to the project root with a section per PRD, linked epic tables, and story counts.
+
+**Typical product workflow:**
+
+```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 full pipeline
+fh product roadmap                         # generate ROADMAP.md
+```
+
+---
+
+### GitHub Integration
+
+```bash
+fh github setup                            # interactive: token + owner/repo; writes ~/.forgehive/credentials.json
+fh github sync                             # fetch open Issues → create Story cards (idempotent)
+fh github pr 42                            # fetch PR #42 metadata + changed files → .forgehive/github-pr-42.md
+```
+
+#### Setup
+
+`fh github setup` prompts for a GitHub personal access token (saved to `~/.forgehive/credentials.json`) and the repository in `owner/repo` format (saved to `.forgehive/github.yaml`). Run once; subsequent commands read the stored config.
+
+#### Issue Sync
+
+`fh github sync` fetches all open GitHub Issues (not PRs) and creates a Story card for each one. It's idempotent — issues already synced (detected by `GitHub: #N` in the story file) are skipped.
+
+```
+✓ Synced: #12 "Add OAuth login"     → US-4
+✓ Synced: #15 "Fix session timeout" → US-5
+→ Skipped: #10 "Refactor auth module" (already synced)
+```
+
+#### PR Context
+
+`fh github pr 42` fetches the PR title, body, author, and full list of changed files, writing a `.forgehive/github-pr-42.md` context file. Share this with a Review Party for structured code review:
+
+```bash
+fh github pr 42
+fh party run review    # Kai + Sam + Eli each see the PR context
+```
+
+---
+
 ### Velocity
 
 ```bash
@@ -637,6 +764,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/
       generated/               <- AI-generated skills (fh skills regen)
@@ -873,9 +1001,9 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
 |---|---|
 | Runtime | Node.js ≥ 18, ESM |
 | Language | TypeScript |
-| Build | esbuild -> `dist/cli.js` (~259 KB, single bundle) |
+| Build | esbuild -> `dist/cli.js` (~293 KB, single bundle) |
 | Type check | `tsc --noEmit` |
-| Tests | `node:test` (native) + tsx ESM loader, 273 tests |
+| Tests | `node:test` (native) + tsx ESM loader, 369 tests |
 | Dependencies | `js-yaml` (sole runtime dependency) |
 
 ```bash
@@ -890,6 +1018,7 @@ npm test            # node --import tsx/esm --test test/*.test.ts
 
 | Version | What's new |
 |---|---|
+| **0.8.0** | GitHub Integration (`fh github setup/sync/pr`), Semantic Repo-Map (`fh map --semantic`), Intelligent Routing (`fh ask`), Product Workflow (`fh product prd/status/roadmap`) |
 | **0.7.7** | User Guide (`docs/user-guide.md`) included in npm package; Documentation table in README |
 | **0.7.6** | YAML shape fix in `fh docs user`; frontmatter regex fix; 8 new tests for HIGH RISK paths |
 | **0.7.5** | `fh --version` reads from `package.json` (no longer hardcoded) |