forgehive 0.7.6 → 0.7.7

package/docs/user-guide.md

@@ -0,0 +1,337 @@
+# forgehive — User Guide
+
+> Version 0.7.6 · [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.
+
+---
+
+## Installation
+
+```bash
+npm install -g forgehive
+```
+
+Requires **Node.js ≥ 18** and **Claude Code** (`claude` CLI). Installs two aliases: `fh` and `forgehive`.
+
+Verify:
+
+```bash
+fh --version   # prints 0.7.6
+fh --help      # full command reference
+```
+
+---
+
+## Quick Start
+
+Three commands to get Claude up to speed on any project:
+
+```bash
+cd my-project
+fh init       # scan the project, write .forgehive/
+fh confirm    # activate the context for Claude
+```
+
+Then open a new Claude Code session in the same directory. Claude reads `.forgehive/` automatically at session start and knows your stack, constraints, and memory.
+
+---
+
+## What `fh init` Does
+
+Running `fh init` in a project:
+
+1. Scans your project — language, framework, dependencies, directory structure
+2. Creates `.forgehive/` with capabilities, memory files, 16 expert skills, agent permissions
+3. Merges a context block into `CLAUDE.md` (creates it if it doesn't exist, never overwrites existing content)
+4. Writes `AGENTS.md` to the project root (works with Cursor, Copilot, Gemini CLI, Codex, Windsurf)
+
+The result looks like this:
+
+```
+my-project/
+  .forgehive/
+    capabilities.yaml     ← detected stack (status: draft → confirmed)
+    harness/
+      constraints.yaml    ← max_lines, require_tests, style rules
+      permissions.yaml    ← per-agent file access control
+    memory/
+      MEMORY.md           ← index of all memory files
+      project.md          ← project context and open decisions
+      feedback.md         ← corrections + confirmed approaches
+      stack.md            ← details the scanner can't detect
+      adrs/               ← Architecture Decision Records
+      stories/            ← story cards (US-N.md)
+      epics/              ← epic cards (EPC-N.md)
+      velocity.md         ← sprint velocity history
+    skills/expert/        ← 16 preinstalled expert skills
+  AGENTS.md
+  CLAUDE.md               ← forgehive block appended, nothing overwritten
+```
+
+**Already have a `.forgehive/`?** `fh init` prints a warning and stops. Use `fh init --force` to re-initialize, or `fh scan --update` to update only the scan.
+
+---
+
+## The Two Statuses: Draft and Confirmed
+
+After `fh init`, `capabilities.yaml` is in `status: draft`. Claude won't treat the context as authoritative until you run:
+
+```bash
+fh confirm
+```
+
+This is intentional — review what the scanner detected before committing to it. Open `capabilities.yaml`, check that the language, framework, and dependencies look right, then confirm.
+
+To check the current status at any time:
+
+```bash
+fh status
+```
+
+---
+
+## Memory — Teaching Claude About Your Project
+
+The memory files in `.forgehive/memory/` are the most important part of forgehive. Claude reads them at every session start. Write to them directly in your editor, or let Claude append to them at session end.
+
+| File | What to put here |
+|---|---|
+| `project.md` | Architecture decisions, goals, open questions |
+| `feedback.md` | Things Claude got wrong, things that worked well |
+| `stack.md` | Auth patterns, deploy targets, things the scanner missed |
+| `adrs/` | Architecture Decision Records |
+
+**Create an ADR:**
+
+```bash
+fh docs adr "Use Postgres over MongoDB"
+fh memory adr list    # list all ADRs
+```
+
+**View all memory:**
+
+```bash
+fh memory show
+```
+
+**Export for sharing:**
+
+```bash
+fh memory snapshot export ./team-memory.json
+fh memory snapshot import ./team-memory.json   # on another machine (skips existing files)
+```
+
+**Share with your team via git:**
+
+```bash
+fh sync push    # push .forgehive/memory/ to a dedicated git branch
+fh sync pull    # pull on another machine
+```
+
+---
+
+## Keeping Context Fresh
+
+Claude's context drifts when the codebase changes significantly. Run:
+
+```bash
+fh scan --check    # is the snapshot still current? (exits 1 if outdated)
+fh scan --update   # re-scan and update capabilities.yaml
+```
+
+Put `fh scan --check` in your CI pipeline to alert when the context needs refreshing.
+
+---
+
+## Documentation
+
+Generate documentation from your project's stack, memory, and git history:
+
+```bash
+fh docs                          # list existing documentation
+fh docs user                     # user guide → docs/user-guide.md
+fh docs api                      # API reference from exports → docs/api.md
+fh docs onboard                  # onboarding doc → ONBOARDING.md
+fh docs changelog                # semantic changelog → CHANGELOG.md
+fh docs changelog --since v1.0   # only changes since a tag
+fh docs adr "<title>"            # Architecture Decision Record
+```
+
+Custom output paths:
+
+```bash
+fh docs user --output ./guides/getting-started.md
+fh docs api  --output ./docs/reference.md
+```
+
+---
+
+## Security
+
+```bash
+fh security scan              # scan for secrets + SAST vulnerabilities
+fh security deps              # check npm dependencies for CVEs
+fh security report            # CISO-ready Markdown report
+fh security report gdpr       # GDPR-specific checks
+fh security report soc2       # SOC 2 relevant controls
+fh security report hipaa      # HIPAA technical safeguards
+fh security audit             # view the JSONL audit trail
+fh security permissions       # show per-agent file access rules
+```
+
+`fh security scan` exits with code 1 if CRITICAL or HIGH findings exist — safe to use as a CI gate. Secrets are never stored verbatim: only the first 6 characters appear in output, followed by `***`.
+
+---
+
+## Story Cards and Sprint Planning
+
+Lightweight agile tracking inside `.forgehive/memory/`:
+
+```bash
+# Epics
+fh epic create "User Authentication" --goal "Users can log in securely"
+fh epic list
+fh epic show EPC-1
+
+# Stories
+fh story create "As a user I want to log in" --epic EPC-1 --points 3
+fh story list
+fh story show US-1
+fh story sprint US-1    # pull into current sprint
+fh story done US-1      # mark done
+fh story done US-1 --points 5   # mark done and record actual points
+
+# Velocity
+fh velocity record sprint-3 --committed 21 --delivered 18
+fh velocity show        # history + rolling average + capacity recommendation
+```
+
+In a Claude Code session, run `/fh-sprint` to let Claude read the backlog and velocity data and suggest a realistic sprint scope.
+
+---
+
+## 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.
+
+```bash
+fh party run              # start the default (build) party
+fh party status           # check active sessions
+fh party cleanup          # remove finished worktrees
+```
+
+**Available party sets — trigger in Claude Code with the slash command:**
+
+| Slash Command | Agents | Use for |
+|---|---|---|
+| `/party` | Viktor + Kai + Sam | Feature development |
+| `/design-party` | Suki + Viktor | UI/UX and architecture |
+| `/review-party` | Kai + Sam + Eli | Code review, tests, docs |
+| `/security-party` | Vera + Sam | Security audit |
+| `/full-party` | All 8 agents | Major releases |
+
+Each agent works in its own worktree branch. After the party completes, review each agent's findings and merge selectively.
+
+---
+
+## Slash Commands in Claude Code
+
+These commands are available inside any Claude Code session in a forgehive-initialized project:
+
+| Command | What it does |
+|---|---|
+| `/fh-sprint` | Sprint planning from backlog + velocity data |
+| `/fh-ship` | Pre-ship checklist: tests, diff, PR draft |
+| `/fh-review` | Structured code review |
+| `/fh-hotfix` | Minimal hotfix protocol (< 50 lines rule) |
+| `/fh-test-this` | Generate tests for the current file |
+| `/fh-docs` | Interactive documentation generation |
+| `/fh-start-task` | Start a new feature branch with full context |
+| `/fh-deploy` | Pre-deploy checklist |
+| `/party` | Start build party (Viktor + Kai + Sam) |
+| `/design-party` | Start design party (Suki + Viktor) |
+| `/review-party` | Start review party (Kai + Sam + Eli) |
+| `/security-party` | Start security party (Vera + Sam) |
+| `/full-party` | Start all 8 agents |
+
+---
+
+## MCP — Connecting External Services
+
+Wire Claude Code to external services in one command:
+
+```bash
+fh wire linear     # Linear issue tracker
+fh wire github     # GitHub
+fh wire slack      # Slack
+fh wire notion     # Notion
+fh wire postgres   # PostgreSQL
+```
+
+Also supported: `sentry`, `jira`, `pagerduty`, `datadog`, `figma`.
+
+Store API keys securely (encrypted at `~/.forgehive/credentials.json`, chmod 600):
+
+```bash
+fh mcp auth add github GITHUB_TOKEN=ghp_yourtoken
+fh mcp auth add linear LINEAR_API_KEY=lin_api_key
+fh mcp auth list           # see which services have credentials
+fh mcp auth remove github  # delete credentials for a service
+```
+
+---
+
+## Cost Tracking
+
+```bash
+fh cost               # all-time Claude session costs
+fh cost today         # today's costs
+fh cost week          # this week
+fh cost --limit 20    # set a hard spend limit of $20
+fh cost --alert 15    # set an alert threshold at $15
+```
+
+Spend limits are enforced every time `fh cost` runs. At the alert threshold: warning printed. At the hard limit: non-zero exit — usable as a CI gate.
+
+---
+
+## CI Integration
+
+```bash
+fh ci                          # CI health report
+fh ci --format markdown        # Markdown output
+fh ci --fail-on high           # exit 1 on HIGH or CRITICAL findings
+fh ci --init                   # scaffold .github/workflows/forgehive.yml
+```
+
+`fh ci` aggregates security scan, dependency audit, and test results. The `--fail-on` flag controls which severity level blocks the pipeline.
+
+---
+
+## Removing forgehive
+
+```bash
+fh rollback
+```
+
+Removes `.forgehive/` and the forgehive block from `CLAUDE.md`. Everything else in `CLAUDE.md` is preserved. `AGENTS.md` is left in place (it's a standard file other tools use too — delete it manually if you don't want it).
+
+---
+
+## Troubleshooting
+
+**`fh init` says forgehive is already initialized**
+Use `fh init --force` to re-initialize, or `fh scan --update` to refresh only the scan.
+
+**Claude doesn't seem to pick up the context**
+Make sure `fh confirm` was run — check `fh status`. The context is inactive while `status: draft`.
+
+**`fh scan --check` exits with an error**
+Your codebase has changed significantly since the last scan. Run `fh scan --update` to refresh.
+
+**Party Mode: worktrees left over after a session**
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "forgehive/"
   ],
   "keywords": [