AGENTS.md

agents.md compatibility — this file orients any AI coding agent (Claude Code, Codex, Cursor, Aider, Continue.dev, OpenClaw, Hermes-Agent, or a custom tools-using LLM) that's working on the open-forge codebase. End users using the open-forge skill to deploy software should look at SKILL.md instead.

Canonical reference. This file is intentionally short. The full architectural treatment, strict-doc-verification policy, two-tier coverage model, sanitization rules, and issue-processing workflow live in CLAUDE.md. Read that for the complete picture — AGENTS.md is the agents.md-standard landing page that points at it.

What this project is

open-forge is a guided self-hosting skill distributed via Claude Code's plugin marketplace and adapted for 6+ other AI platforms. It walks users from "I have a cloud account and a domain" to "working app at https://my.domain" via a phased workflow (preflight → provision → dns → tls → smtp → inbound → hardening → feedback) using 2,200+ verified recipes plus curated bundles for goal-shaped requests (AI homelab, privacy stack) plus a live-derived fallback for the long tail.

This isn't a typical software repo — it's a library of platform-agnostic markdown recipes + a thin Bash build script. There's no compiled artifact, no test suite, no lint config. The "build" is regenerating distribution bundles from canonical sources.

Working on this repo — the rules

Per CLAUDE.md:

1. No human PRs — issues only. Catalog evolves through GitHub issues processed by AI sessions. See .github/ISSUE_TEMPLATE/ for the three input channels (recipe-feedback, software-nomination, method-proposal). Direct PRs are discouraged; if you submit one, the strict-doc policy still applies.
2. Strict-doc-verification policy. Every install method in every recipe must cite an upstream URL (> **Source:** <url>). Community-maintained methods open with the required ⚠️ blockquote. The README is necessary but not sufficient — also read the upstream docs site, repo docs/install/ tree, and wiki. If upstream-doc fetch fails, stop; do not write speculative content. Full rules in CLAUDE.md § Strict doc-verification policy.
3. Sanitization principles. User-shared content (deploy logs, gotchas, error output) must be stripped of identifiers (domains, IPs, SSH keys, API keys, AWS account IDs, emails) before being merged into recipes or posted to GitHub issues. Full strip-list with regex patterns in CLAUDE.md § Sanitization principles.
4. Two-tier coverage model. Tier 1 = verified recipes in references/projects/. Tier 2 = live-derived from upstream docs at runtime for software not yet in the catalog. Promotion criteria in CLAUDE.md § Two-tier coverage model.
5. In-scope test. Before adding a recipe: deployable service / static-site generator / CLI agent / AI inference server / CI runner / storage backend → ✅. Library / desktop app / SaaS-only → ❌. Decision rule + edge-case table in CLAUDE.md § Is this software in scope?.

Build / test / lint

There is no traditional build / test / lint pipeline. The single build artifact is the multi-platform distribution bundles under dist/:

./scripts/build-dist.sh all          # regenerate bundles for all 7 platforms
./scripts/build-dist.sh codex        # just Codex
./scripts/build-dist.sh openclaw     # just OpenClaw

Required after touching any of: CLAUDE.md, plugins/open-forge/skills/open-forge/SKILL.md, plugins/open-forge/skills/open-forge/references/modules/*.md. The bundles concatenate these files; they drift if not regenerated, which silently breaks non-Claude-Code platforms.

CI enforces this — see .github/workflows/dist-bundles.yml. If the dist-bundles-up-to-date check fails on your PR, the fix is always: run ./scripts/build-dist.sh all from the repo root, commit the changes, push.

Versioning

plugins/open-forge/.claude-plugin/plugin.json version controls what the Claude Code marketplace fetches.

• Bump on: skill description change, new project / runtime / infra / module, major recipe rewrite, anything user-visible.
• Don't bump on: typo fixes, internal cleanups, lint-only changes.

Author convention

Commits authored as Qi Zhang <zhangqi444@gmail.com> — set inline via env vars (GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL). Never write to git config.

Recommended companion skill — garrytan/gstack

If you're a Claude Code session working on this repo, install garrytan/gstack — Garry Tan's SDLC slash-command bundle. Its /review, /qa, /ship, /cso, /learn, and /plan-eng-review commands map directly onto the maintenance workflows used here. Install:

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack \
  && cd ~/.claude/skills/gstack && ./setup

See CLAUDE.md § Recommended companion: garrytan/gstack for the per-command mapping. Optional but encouraged.

Per-platform integration (when working on platform-specific bits)

If your patch touches platform-specific behavior, check the per-platform integration docs:

• Claude Code — canonical platform; auto-discovers via plugin marketplace
• Codex — system-prompt embedding or workspace files
• Cursor — .cursor/rules/ bundle
• Aider — --read flags + CONVENTIONS.md
• Continue.dev — context provider + slash command
• OpenClaw — workspace skill
• Hermes-Agent — user skill
• Generic agents — any tools-using LLM

Cross-platform behavior changes (e.g. credential handling) live in references/modules/ so all platforms inherit them through the dist bundles.

Reference

For everything not covered above:

• BRD.md — intent: why the project exists, who it's for, success criteria, what we're explicitly not building.
• CLAUDE.md — policy: what's in scope, strict-doc rules, sanitization, processing workflow.
• ARCHITECTURE.md — system shape: actors, data flow, state stores, quality gates, cadence.

User-facing project documentation lives in README.md. End-user-skill content lives in plugins/open-forge/skills/open-forge/SKILL.md.

Tell Claude Code what to self-host. It does the rest — picks the right install method, provisions the server, configures DNS + TLS, sets up SMTP, hardens it, and brings the app up at your domain.

No more reading a 30-step README and copy-pasting bash for hours. You stay in chat; Claude Code drives the CLIs (aws, gcloud, kubectl, docker, ssh, …) and asks you only the things only you can answer (which cloud, which domain, which credential).

Backed by a self-improving catalog: every deploy can feed gotchas back so the next user starts further ahead.

> "Self-host OpenClaw on AWS Lightsail with Bedrock pre-wired."

  Claude Code: Loading verified recipe openclaw.md (v0.24.0).
  Claude Code: Combo: AWS Lightsail OpenClaw blueprint (vendor-bundled, Bedrock IAM included).
  Claude Code: I'll need your AWS profile and the domain you want.

  AWS profile name?

(OpenClaw — the self-hosted personal AI agent at openclaw.ai — is the project's signature use case; works the same way for any of the 2,200+ verified recipes.)

Install in Claude Code

/plugin marketplace add zhangqi444/open-forge
/plugin install open-forge@open-forge

That's it. From now on, just say what you want self-hosted in any Claude Code session:

"Self-host Vaultwarden on my laptop, expose via Cloudflare Tunnel."

"Run Immich on a Hetzner CX22 with restic backups to Backblaze B2."

"Deploy Ghost on AWS Lightsail at blog.mydomain.com."

Also works on other AI coding tools and agent platforms

Claude Code is the canonical home, but the same recipes ship for other agents — see docs/platforms/:

Platform	How
Codex (ChatGPT / CLI)	System-prompt embedding or workspace files
Cursor	.cursor/rules/ bundle
Aider	--read files + CONVENTIONS.md
Continue.dev	Context provider + slash command
OpenClaw (personal AI agent at openclaw.ai)	Workspace skill at ~/.openclaw/workspace/skills/open-forge/
Hermes-Agent (Nous Research)	User skill at ~/.hermes/skills/open-forge/
Generic agents	Any LLM that can read files + run shell

Agent-mode caveat: When running inside an autonomous agent (OpenClaw / Hermes / messaging-channel agents), credential paste is disabled — the skill only accepts file paths, env vars, cloud-CLI sessions, or secrets-manager refs. Pasting credentials into messaging channels (WhatsApp / Telegram / etc.) is meaningfully riskier than into coding-tool chat. Group-channel deploy conversations are also refused.

On Windows? See docs/windows-setup.md for WSL2 + Docker Desktop setup and common Windows gotchas (stale Git proxy, line endings, WSL integration).

Updates

To know when a new version ships:

• 📋 CHANGELOG.md — user-visible changes per version
• 📡 Releases atom feed — subscribe in any feed reader (Feedbin, Inoreader, NetNewsWire)
• 🌟 GitHub Watch → Custom → Releases — email notification on each release

To apply an update in Claude Code: /plugin marketplace update zhangqi444/open-forge

Why use open-forge instead of asking Claude Code directly?

Raw Claude Code can absolutely deploy software for you — but it starts from zero every session. open-forge accumulates — every deploy can feed gotchas back into the catalog so the next user starts further ahead.

   you deploy ─► skill captures gotchas ─► you review + opt in to share
        ▲                                         │
        │                                         ▼
        └─ improved recipe ◄─ AI agent patches ◄─ sanitized issue

The loop:

1. You deploy. Skill walks you through provisioning, DNS, TLS, SMTP, hardening — recording state for resume.
2. Skill drafts a sanitized issue at the end with the gotchas it observed and proposed recipe edits. Domains, IPs, API keys, AWS account IDs are stripped before you see the draft.
3. You review and opt in (or don't — never auto-posted). One click; takes seconds.
4. An AI agent processes the issue — re-fetches upstream docs, applies the strict doc-verification policy, patches the recipe, opens a PR, bumps the version.
5. The next user gets the improved recipe.

That's why captured tribal knowledge already includes things like "OpenClaw's three installers (install.sh, install-cli.sh, install.ps1) don't share state — pick one and stick with it", "the Lightsail OpenClaw blueprint runs the gateway as a systemd USER unit with loginctl enable-linger so it survives no-login sessions", "on Windows, OpenClaw's iwr | iex failures are non-fatal to the shell — silent partial installs are common, always check the explicit success line", and "Bitnami's bncert-tool won't accept --unattended" — none of which are in any upstream README.

Other reasons it's better than raw Claude Code:

• Resumable across sessions — phased workflow + state file at ~/.open-forge/deployments/<name>.yaml. If TLS fails at 11pm, resume from the tls phase tomorrow.
• Consistent across clouds — "install Docker on Ubuntu" is written once and reused for Hetzner / DO / Lightsail / localhost. Swap clouds without re-deriving.
• Source-attributed — every install method cites the upstream URL it derives from. When upstream drifts, the link is the recovery path.
• Safer credential handling — five patterns ordered by safety (file path → env var → cloud-CLI session → secrets manager → chat paste); chat paste asks you to acknowledge the risk and reminds you to rotate after.

Coverage

• Software: 2,200+ verified recipes for popular self-hostable apps — AI stack (Ollama · vLLM · Open WebUI · …), publishing (Ghost · WordPress · …), productivity (Nextcloud · Joplin · …), photos & media (Immich · Jellyfin · …), monitoring, security, networking, communication, automation. Plus curated bundles (AI homelab, privacy stack) for goal-shaped requests, and live-derived fallback for anything else with public docs (best-effort; you'll see a banner before it starts).
• Where: any cloud VM (AWS · Azure · GCP · Hetzner · DigitalOcean · Oracle Always-Free ARM · Hostinger), your own machine, Raspberry Pi, macOS VM (Lume), any Kubernetes cluster (EKS · GKE · AKS · DOKS · k3s · kind), or PaaS (Fly.io · Render · Railway · Northflank · exe.dev).
• How: Docker · Podman · Native · Kubernetes (Kustomize-first; Helm where upstream ships one).

📖 Browse the catalog: deepwiki.com/zhangqi444/open-forge — auto-generated wiki view of every recipe, infra adapter, and module. Stays current with the repo.

Or just tell Claude Code — "self-host X on Y" — and it'll match.

Contributing

File an issue, don't open a PR. Issue templates cover three channels:

• Recipe feedback — the skill drafts this for you at end of deploy (sanitized; you opt in)
• Software nomination — request a recipe for an app the catalog doesn't have
• Method proposal — an upstream install method an existing recipe doesn't cover

An AI agent reads CLAUDE.md as its runbook, re-verifies every change against upstream docs, and patches the catalog. Why issues, not PRs? Central verification keeps the catalog consistent, and the skill sanitizes drafts before posting so credentials don't leak into commit history.

For how the catalog is maintained as a system (actors, data flow, state stores, quality gates), see ARCHITECTURE.md. For policy details (3-axis model, strict-doc-verification policy, two-tier coverage, sanitization rules), see CLAUDE.md. For project intent (why / who / success / non-goals), see BRD.md.

License

MIT — fork freely, attribution appreciated.