forge-workflow 0.0.10 → 0.1.0-beta.3

package/skills/kernel/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: kernel
+description: >
+  Forge kernel — umbrella index/router for a Forge project. Reach for this FIRST when
+  orienting rather than executing: at session start, when you need the map of how the system
+  fits together, or when unsure WHICH skill or `forge` verb a task belongs to. It indexes
+  `smith` (end-to-end orchestrator), the stage ladder (plan → dev → validate → ship → review →
+  verify), the utility/issue skills, and the day-to-day `forge` CLI verbs. Trigger on "how
+  does the Forge workflow work", "which forge command or skill for X", "I'm new here, how is
+  Forge set up", or "should this be a Forge issue or a TodoWrite". Index layer only — hand off
+  the doing: rank/pick the next ready issue → `triage-ready`; current stage / "where am I" /
+  active or stale work → `status`; create/update/close/search one issue → `issue-basics`;
+  claim-then-prove ownership before mutating → `claim-safety`; drive one issue from plan to a
+  merged PR under gates → `smith`; token-bounded state for the Hermes harness →
+  `hermes-forge`.
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Forge kernel surface
+
+Forge is a TDD-first workflow harness. The agent-facing surface is **skills + the
+`forge` CLI** — there are no slash-command files. This umbrella skill is the
+entry point: it tells you which stage skill to use and which `forge` verb runs
+each day-to-day operation. Every skill is a thin guide over a real `forge`
+command; the CLI remains the implementation, the skills are the surface.
+
+## Stage skills (the TDD ladder)
+
+The default workflow is a configurable ladder of per-stage skills. Use the whole
+flow when it fits, or invoke an individual stage when the active plan permits a
+smaller path.
+
+| Stage | Skill | Purpose |
+|-------|-------|---------|
+| utility | `status` | Check current context, active work, recent completions |
+| 1 | `plan` | Design intent → research → branch + worktree + task list |
+| 2 | `dev` | Subagent-driven TDD per task (implementer → spec → quality review) |
+| 3 | `validate` | Type check, lint, code review, security, tests — all fresh output |
+| 4 | `ship` | Push branch and open the PR with design-doc reference |
+| 5 | `review` | Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud) |
+| 6 | `verify` | Post-merge health check (CI on main, close issues) |
+
+**Pre-merge gate** (not a numbered stage): before merge, finish the doc updates on
+the feature branch and confirm CI is green, then hand off the PR for manual merge.
+The gate is embedded in `ship` and `review` — it is not a standalone skill.
+
+Utility skills outside the linear ladder: `research` (deep web research),
+`rollback` (safe revert operations), `sonarcloud` (code-quality queries),
+`shepherd` (cross-harness PR monitoring).
+
+Procedure skills (reusable operations any stage/agent embeds): `claim-safety`
+(claim an issue and PROVE you own the lease via `forge issue owns <id>` before
+mutating it — a claim returning ok:true does not by itself prove ownership).
+
+```
+status → plan → dev → validate → ship → review → verify
+```
+
+## Orchestrator super-skill
+
+`smith` is the flagship: a thin orchestrator that COMPOSES the skills above into
+the right path for a piece of work — pick (`triage-ready`) → claim
+(`claim-safety`) → `plan` → `dev` → `validate` → `ship` → `review` → `verify` —
+driving autonomously between human gates and pausing AT them. The human gates are
+durable kernel EVENTS (`forge gate check|approve|reject|status <issue> <gate>`;
+gates `gate.intent` · `gate.plan-approval` · `gate.merge`), so a gated run is
+resume-safe across compaction. During planning `smith` calibrates how many gates
+the work needs from its size × importance × complexity and proposes that tier at
+the intent gate (the human confirms or overrides). Reach for `smith` to run a
+whole issue end to end under human control; invoke an individual stage skill to
+run a single step.
+
+## Kernel-native skills
+
+Read-and-repair skills that work directly against the kernel's issue store. They
+complement the ladder: reach for them to decide *what* to do and to run the
+everyday issue operations, then route into a stage skill to execute.
+
+| Skill | Purpose |
+|-------|---------|
+| `triage-ready` | Read-only "what should I work on" — ranks and *explains* the ready queue via `forge issue ready` / `blocked` / `stats` (never `board`), then hands off the pick. |
+| `issue-basics` | The everyday CRUD floor — create/update/claim/release/comment/close/show/list/search/stats over the `forge issue` verbs, plus the label/reopen/delete disposition for teams migrating in. |
+
+## Day-to-day verbs (the `forge` CLI)
+
+The kernel verbs are the operations you reach for inside any stage — find work,
+claim it, fix in place, query the board, orient. They are grouped in four
+families. Run them through Bash; never hand-edit the issue store.
+
+### A — Issue lifecycle (the core loop)
+
+| Need | Command |
+|------|---------|
+| Find ready work | `forge ready [--json]` |
+| Inspect an issue | `forge show <id> [--json]` |
+| List / filter issues | `forge list [--status …] [--json]` |
+| Create an issue | `forge create --title "…" --type <feature\|bug\|task>` |
+| Claim work (DB-enforced lease) | `forge claim <id>` |
+| Prove you own the lease | `forge issue owns <id>` — exit 0 iff you hold the live lease (see the `claim-safety` skill) |
+| Release a claim | `forge release <id>` |
+| Update fields | `forge update <id> --priority <n>` (etc.) |
+| Add a handoff comment | `forge comment <id> "…"` |
+| Close an issue | `forge close <id> --reason "…"` |
+| Dependencies | `forge issue dep add\|remove <id> <id>` |
+| Search / stats | `forge issue search "…"` · `forge issue stats` |
+| Blocked work | `forge blocked` |
+
+### B — Memory / knowledge
+
+`forge remember <note> [--tag <label>]... [--json]` and `forge recall` are live —
+they persist and retrieve project-memory notes from a file-backed store. Only
+`forge knowledge search` is not on the CLI yet; until it lands, capture durable
+decisions as `forge remember` notes or issue comments (`forge comment`).
+
+### C — Board / planning / admin
+
+| Need | Command |
+|------|---------|
+| Team board | `forge board [--json]` |
+| Export the issue projection | `forge export [--import]` |
+| Release-readiness gate | `forge release check --target <ref>` |
+| Sync team state | `forge sync` |
+
+### D — Orientation / session
+
+| Need | Command |
+|------|---------|
+| Prime a session | `forge prime [--json]` |
+| Full orientation | `forge orient [--json]` |
+| Recap an issue / context | `forge recap [<id>] [--json]` |
+
+## Forge issues vs. TodoWrite — decision table
+
+| Situation | Use |
+|-----------|-----|
+| Work spans sessions, has blockers, or needs recovery after compaction | **Forge issues** (`forge create`/`claim`/`close`) |
+| Cross-agent or cross-worktree coordination | **Forge issues** (DB-enforced leases) |
+| Durable decisions, design rationale, handoff notes | **Forge issue comments** |
+| Ephemeral, single-session checklist for the current task | **TodoWrite** |
+| Steps you will finish and discard within this turn | **TodoWrite** |
+
+When in doubt, prefer a Forge issue: it survives the session and is visible to
+the team. TodoWrite is for scratch tracking only.
+
+## Session protocol
+
+1. **Orient first.** Start with the `status` skill (or `forge prime` /
+   `forge orient`) — never reconstruct project state from raw files.
+2. **Claim before you build — then prove it.** `forge claim <id>` takes the lease;
+   one issue at a time. A claim's ok:true does not by itself prove ownership, so
+   confirm with `forge issue owns <id>` before working and again before
+   `close`/`release` (the `claim-safety` skill). `forge release <id>` if you abandon it.
+3. **Work the ladder.** `plan` → `dev` → `validate` → `ship` → `review` →
+   `verify`, skipping stages only when the plan allows. The pre-merge doc gate
+   runs inside `ship` and `review` before merge — it is not a separate stage.
+4. **Record evidence as you go.** Progress and decisions go to
+   `forge comment <id> "…"`, not to memory.
+5. **Hand off cleanly.** Close completed issues (`forge close <id> --reason …`)
+   and `forge sync` so the team sees the result.
+
+## Core principles
+
+- **TDD-first** — write tests before implementation (RED → GREEN → REFACTOR).
+- **Research-first** — understand before building; document decisions.
+- **Security built-in** — OWASP Top 10 analysis for every feature.
+- **Documentation progressive** — update at each stage, verify at the end.

package/skills/kernel/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "I just cloned this Forge repo and I'm not sure how any of it works — give me the lay of the land: what's the workflow, what skills exist, and where do I even start?",
+    "should_trigger": true
+  },
+  {
+    "query": "There are a bunch of forge skills and I can't tell which one to use for what — lay out how they fit together and when I'd reach for each.",
+    "should_trigger": true
+  },
+  {
+    "query": "Which forge CLI command adds a dependency between two issues, and what's the verb for proving I hold a claim? Just the reference, don't run anything.",
+    "should_trigger": true
+  },
+  {
+    "query": "Is this small cleanup worth filing as a Forge issue, or should I just throw it on a TodoWrite checklist for this session?",
+    "should_trigger": true
+  },
+  {
+    "query": "Walk me through the Forge stage ladder from planning to post-merge verify and what each stage owns.",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the reference of all the day-to-day forge issue and board verbs — I want the index, not to execute a command yet.",
+    "should_trigger": true
+  },
+  {
+    "query": "What should I pick up next? Rank the ready queue and tell me the top unblocked issue and why.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now, what's my active work, and has anything gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a bug issue titled 'login times out after 30s', priority 1, and link it under the auth epic.",
+    "should_trigger": false
+  },
+  {
+    "query": "Claim forge-4h9 for me and confirm I actually hold the lease before I start editing.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-7c2 all the way from planning through a merged PR, pausing for my approval at the plan and the merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "In the Hermes harness, give me the token-bounded project state to work from — treat forge orient as the source of truth.",
+    "should_trigger": false
+  }
+]

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
   }
 ]