forge-workflow 0.0.10 → 0.1.0-beta.2

package/skills/memory/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: memory
+description: >
+  Capture and retrieve durable project memory the right way -- and, when the graph
+  backend is enabled, use temporal knowledge-graph memory. Reach for this whenever
+  you are about to write down a lasting fact, decision, convention, or gotcha ("remember
+  that...", "note for later", "save this"), or when you need to recall what was learned
+  before ("what did we decide about X", "have we seen this"). It explains WHEN to use
+  `forge remember` / `forge recall` versus a per-issue `forge issue comment`, how the
+  two public backends work (local JSONL default, opt-in Graphiti; kernel is internal-only),
+  and -- when Graphiti is enabled -- how to add episodes and search facts via the graphiti-memory MCP tools
+  (add_memory, search_memory_facts, search_nodes) with group_id scoping and provenance.
+  The local backend is always the offline floor. Not for: issue create/list/close ops
+  (issue-basics), workflow status (status), or transient scratch notes.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Memory
+
+Durable project memory for agents. This skill teaches you where a fact belongs,
+which backend is active, and how to use graph memory when it is enabled.
+
+## The one rule
+
+Persistent, project-level knowledge goes to **`forge remember`** — never to a
+`MEMORY.md` file, never to a scratch note that dies with the session. Retrieve it
+with **`forge recall`**. Both verbs route through one backend router; the default
+is a local file store, so they always work offline with zero setup.
+
+## When to use what
+
+- **`forge remember "<note>"`** — a lasting fact that outlives this issue: a
+  convention, a decision and its rationale, a non-obvious gotcha, an environment
+  quirk, a "we tried X, it failed because Y". Add `--tag <label>` for retrieval.
+- **`forge recall "<query>"`** — before assuming, check what is already known.
+  Search first; do not re-derive knowledge the project already recorded.
+- **`forge issue comment <id> "<note>"`** — progress or context that belongs to
+  ONE issue's lifecycle (status, a blocker, a hand-off). Issue-scoped, not global.
+- **Rule of thumb:** would a future session on a *different* issue want this? →
+  `remember`. Is it only meaningful inside this issue? → `issue comment`.
+
+## Backends (config: `memory.backend` in `.forge/config.yaml`)
+
+The router picks a backend; `remember`/`recall` behave the same from your side.
+The public backends are exactly two:
+
+- **`local`** (DEFAULT) — flat JSONL at `.forge/memory/notes.jsonl`. Instant,
+  offline, no dependencies, travels with the repo in git. This is the floor and
+  is always available.
+- **`graphiti`** — opt-in temporal **knowledge graph** served to agents over MCP.
+  Richer recall (relational, temporal, provenance-tracked) but needs a graph DB
+  and an LLM. See "Graph memory" below. When selected, the CLI still writes to
+  the local store as a safety floor; the graph is consumed by agents via MCP.
+
+Check the active backend with `forge doctor` — it reports the memory backend and,
+for graphiti, whether the configured MCP server path is present (read-only,
+non-fatal).
+
+## Graph memory (when `memory.backend: graphiti`)
+
+Graphiti turns notes into a **bi-temporal knowledge graph**: you add *episodes*
+(text/JSON), an LLM extracts *entities* (nodes) and *facts* (edges), and every
+fact keeps two timelines — when it was true in the world and when the system
+learned it. Superseded facts are **invalidated, not deleted**, so you can ask
+"what is true now" or "what was true at time T", with a pointer back to the
+source episode (provenance).
+
+When enabled and the `graphiti-memory` MCP server is wired into your agent, use
+its tools directly:
+
+- **`add_memory`** — record a durable fact/decision as an episode. Pass a clear
+  `name`, the content, and the project `group_id` (namespaces one project's
+  memory). Ingestion is LLM-backed, so treat it as async — confirm it queued,
+  don't block on it. Prefer this for facts that *evolve* (status, ownership,
+  versions, preferences).
+- **`search_memory_facts`** — retrieve relationships/facts (edges) for a query,
+  with validity windows. Use this before assuming a fact; it returns *current*
+  truth plus history.
+- **`search_nodes`** — find entities (people, services, components) and their
+  summaries.
+- Scope every call with the project's `group_id` so memory stays per-project.
+- Respect provenance: facts trace back to episodes — cite them when it matters.
+
+If graph memory is unreachable or unconfigured, fall back to `forge remember`
+(local) — never lose the note. `forge doctor` surfaces a clear error when the
+graphiti backend is selected but not configured.
+
+## Good memory hygiene
+
+- Write **atomic** facts, not essays — one decision or gotcha per note.
+- Include the **why**, not just the what (rationale ages better than commands).
+- Tag consistently so recall is precise.
+- Recall **before** you act on an assumption; record **after** you learn something.
+
+## Setup pointers
+
+- Local is the default — nothing to install.
+- To opt into graph memory: set `memory.backend: graphiti` (plus a
+  `memory.graphiti` block) in `.forge/config.yaml`, then run FalkorDB + the
+  Graphiti MCP server. Wiring the server into each agent's MCP config is a
+  follow-up step. Full how-to (graph DB, LLM/embedder, privacy/cost):
+  `docs/guides/memory-backends.md`. Design rationale: `docs/work/2026-07-06-graphiti-memory/research.md`.

package/skills/parallel-deep-research/SKILL.md

@@ -1,17 +1,18 @@
 ---
 name: parallel-deep-research
 description: >
-  Produces comprehensive research reports that go far beyond what built-in web
-  search can achieve. Sends research tasks to Parallel AI's pro/ultra processors
-  which spend 3-25 minutes autonomously crawling, reading, and synthesizing dozens
-  of sources — returning structured reports with citations. Built-in WebSearch
-  can only run a few queries; this skill runs an entire research pipeline externally.
-  No binary install — requires PARALLEL_API_KEY in .env.local. ALWAYS use this
-  skill instead of doing multiple WebSearch calls when the user needs a comprehensive
-  report, market analysis, competitive landscape, industry deep-dive, strategic
-  recommendations, or multi-source synthesis. This is the RIGHT tool for any
-  research task that would require more than 3-4 web searches to answer properly.
-  Also trigger during /plan Phase 2 research and /research workflows.
+  Heavyweight EXTERNAL research reports — market, industry, competitive, strategic — via
+  Parallel AI's paid pro/ultra processors that crawl and synthesize dozens of sources into one
+  long cited report. Use when the user wants a market analysis, competitive landscape,
+  industry deep-dive, multi-vendor/technology comparison, strategic recommendations, or market
+  sizing/growth outlook — any multi-source synthesis needing more than 3-4 web searches.
+  Typical phrasings: "market analysis of X", "competitive landscape comparing A/B/C",
+  "industry deep-dive on...", "deep research report on...", "strategic report with predictions
+  for 2027". WRONG tool for quick facts, a single-page fetch, one-URL scraping, or small
+  structured-field extraction — use built-in WebSearch/WebFetch. Also NOT the Forge RESEARCH
+  or PLAN stage: "run the research stage", "do Phase 2", or codebase/OWASP/DRY investigation
+  into a design doc route to `research` and `plan` (they may INVOKE this skill). Requires
+  PARALLEL_API_KEY.
 compatibility: Requires PARALLEL_API_KEY in .env.local. Uses curl. Takes 3-25 minutes.
 metadata:
   author: harshanandak
@@ -22,6 +23,8 @@ metadata:
 
 Comprehensive research reports with multi-source synthesis. Use `pro` (3-9 min, $0.10) or `ultra` (5-25 min, $0.30) for deep analysis.
 
+> **Safety:** The `input` is transmitted to Parallel AI's external service and may be logged or retained. Never include secrets, API keys/tokens, PII, or private/proprietary repo content — send only information safe to share with a third party.
+>
 > **CLI alternative (recommended)**: Install `parallel-cli` for official skill:
 > `npx skills add parallel-web/parallel-agent-skills --skill parallel-deep-research`
 

package/skills/parallel-deep-research/evals/evals.json

@@ -1,62 +1,46 @@
 [
   {
-    "query": "I need a comprehensive market analysis of the developer tools space — cover the top 20 players, their funding, market positioning, and where the industry is heading over the next 3-5 years. Include data from Gartner, Forrester, and any recent VC investment reports",
+    "query": "I need a comprehensive market analysis of the developer-tools space — top 20 players, their funding, market positioning, and where the industry is heading over the next 3-5 years, pulling from Gartner, Forrester, and recent VC investment reports",
     "should_trigger": true
   },
   {
-    "query": "Write a deep research report on the state of WebAssembly adoption in production — synthesize case studies from companies using WASM, performance benchmarks vs native code, ecosystem maturity analysis, and strategic recommendations for when to adopt it",
+    "query": "Write a deep research report on WebAssembly adoption in production — synthesize company case studies, performance benchmarks vs native code, ecosystem maturity, and clear recommendations for when to adopt it",
     "should_trigger": true
   },
   {
-    "query": "Our CTO wants a competitive landscape analysis comparing Convex, Supabase, Firebase, and PlanetScale for our backend rewrite. Need comprehensive feature comparison, pricing analysis at our scale (50K DAU), community health metrics, and risk assessment for each",
+    "query": "Competitive landscape comparing Convex, Supabase, Firebase, and PlanetScale for our backend rewrite — full feature comparison, pricing at 50K DAU, community-health metrics, and a per-vendor risk assessment",
     "should_trigger": true
   },
   {
-    "query": "Create a strategic report on the AI code generation market — analyze GitHub Copilot, Cursor, Claude Code, and emerging competitors. Cover adoption rates, developer satisfaction surveys, enterprise pricing trends, and predictions for 2027",
+    "query": "Give me an industry deep-dive on the observability market — Datadog vs Grafana Cloud vs New Relic across features, pricing, scalability, and OpenTelemetry support, with customer migration stories and TCO analysis for a 500-node cluster",
     "should_trigger": true
   },
   {
-    "query": "I'm doing /plan Phase 2 research — produce a comprehensive analysis of event-driven architecture patterns in microservices, covering Kafka vs RabbitMQ vs NATS, with production case studies, failure mode analysis, and recommendations for our 100K events/sec throughput requirement",
+    "query": "For our architecture decision, produce a heavily-sourced report on event-driven patterns — Kafka vs RabbitMQ vs NATS at 100K events/sec, with production case studies and failure-mode analysis",
     "should_trigger": true
   },
   {
-    "query": "Write an industry deep-dive into the observability market — compare Datadog, Grafana Cloud, and New Relic across features, pricing, scalability, and OpenTelemetry support. Include customer migration stories and TCO analysis for a 500-node cluster",
-    "should_trigger": true
-  },
-  {
-    "query": "Research and synthesize the current state of edge computing for real-time AI inference — cover hardware options, cloud provider edge offerings, latency benchmarks, and case studies from autonomous vehicles and IoT deployments",
-    "should_trigger": true
-  },
-  {
-    "query": "Quick search: what's the current price of Bitcoin and what were Anthropic's latest announcements?",
-    "should_trigger": false
-  },
-  {
-    "query": "Find the official migration guide URL for ESLint's new flat config format",
-    "should_trigger": false
-  },
-  {
-    "query": "Search for recent blog posts about Bun 2.0 features and release date",
+    "query": "Quick — what's the current price of Bitcoin and what were Anthropic's latest announcements?",
     "should_trigger": false
   },
   {
-    "query": "Go to https://stripe.com/docs/api and extract the authentication section with all the code examples",
+    "query": "Go to https://stripe.com/docs/api and extract the authentication section with all its code examples",
     "should_trigger": false
   },
   {
-    "query": "Scrape https://openai.com/pricing and extract the per-token costs for each model tier",
+    "query": "Scrape https://openai.com/pricing and pull out the per-token cost for each model tier",
     "should_trigger": false
   },
   {
-    "query": "Build a structured company profile for Databricks — return JSON with founding year, funding rounds, valuation, employee count, and tech stack",
+    "query": "Run the /research stage for the auth-refactor feature — investigate how our codebase currently handles session tokens, flag OWASP and DRY concerns, and write the findings into the design doc",
     "should_trigger": false
   },
   {
-    "query": "Fix the TypeScript compilation error in src/services/auth.ts — it's complaining about missing type for the session token",
+    "query": "Kick off the plan stage for adding rate limiting — brainstorm the design one question at a time, then set up the branch, worktree, and task list",
     "should_trigger": false
   },
   {
-    "query": "Add unit tests for the rate limiter middleware in src/middleware/rateLimit.ts",
+    "query": "Fix the TypeScript compilation error in src/services/auth.ts about the missing session-token type",
     "should_trigger": false
   }
 ]