diff --git a/.claude/commands/sync-docs.md b/.claude/commands/sync-docs.md new file mode 100644 index 0000000..f7f050d --- /dev/null +++ b/.claude/commands/sync-docs.md @@ -0,0 +1,62 @@ +# Sync Documentation + +After feature work, update the affected documentation to reflect code changes. + +## Steps + +1. **Identify changed files** — Run `git diff main --name-only` to find modified Go files. + +2. **Map files to docs** — Use this mapping to determine which docs need updates: + + | Changed path pattern | Affected docs | + |---------------------|---------------| + | `forge-core/runtime/` | `docs/runtime.md`, `docs/hooks.md` | + | `forge-core/security/` | `docs/security/overview.md`, `docs/security/egress.md` | + | `forge-core/tools/` | `docs/tools.md` | + | `forge-core/llm/` | `docs/runtime.md` | + | `forge-core/memory/` | `docs/memory.md` | + | `forge-core/scheduler/` | `docs/scheduling.md` | + | `forge-core/secrets/` | `docs/security/secrets.md` | + | `forge-core/skills/` | `docs/skills.md` | + | `forge-core/channels/` | `docs/channels.md` | + | `forge-cli/cmd/` | `docs/commands.md` | + | `forge-cli/runtime/` | `docs/runtime.md` | + | `forge-cli/server/` | `docs/architecture.md` | + | `forge-cli/channels/` | `docs/channels.md` | + | `forge-cli/tools/` | `docs/tools.md` | + | `forge-plugins/` | `docs/channels.md`, `docs/plugins.md` | + | `forge-ui/` | `docs/dashboard.md` | + | `forge-skills/` | `docs/skills.md` | + | `forge.yaml` / `types/` | `docs/configuration.md` | + +3. **Read the diff** — For each mapped doc, read the relevant `git diff main` output to understand what changed. + +4. **Update docs** — For each affected doc: + - Read the current doc file + - Identify sections that need updating based on the code changes + - Edit the doc to reflect new behavior, flags, types, or configuration + - Preserve the navigation footer and header + +5. **Check cross-references** — If you added a new feature/section, ensure: + - The README.md documentation table links to it (if it's a new doc) + - Related docs cross-link to it where appropriate + - Navigation order is still correct + +6. **Validate** — Run a quick broken-link check: + ```bash + grep -rn '\[.*\](.*\.md)' README.md docs/ | while read line; do + file=$(echo "$line" | grep -oP '\(.*?\.md\)' | tr -d '()') + dir=$(dirname "$(echo "$line" | cut -d: -f1)") + target="$dir/$file" + [ ! -f "$target" ] && echo "BROKEN: $line" + done + ``` + +## Rules + +- One topic per file; split if >300 lines +- Start each doc with a one-sentence summary +- Use tables over bullet lists for comparisons +- Link, don't repeat — cross-reference other docs +- Keep ASCII diagrams (they render everywhere) +- Code examples must be runnable diff --git a/README.md b/README.md index a49010d..e4129fa 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,30 @@ -# Forge — Secure Portable AI Agent Runtime +# Forge — Secure, Portable AI Agent Runtime -## What is Forge? - -Forge is a secure, portable AI agent runtime that allows developers to run AI agents locally, in cloud, or in enterprise environments without exposing inbound tunnels. - -Forge enables: -- Atomic agent execution -- Secure outbound-only connectivity -- Portable skill-based agents -- Channel connectors (Slack, Telegram) -- Cron scheduling -- Enterprise-grade identity support - ---- +Build, run, and deploy AI agents from a single `SKILL.md` file. +Secure by default. Runs anywhere — local, container, cloud, air-gapped. ## Why Forge? -**Instant Agent From a Single Command** - -Write a SKILL.md. Run `forge init`. Your agent is live. - -The wizard configures your model provider, validates your API key, -connects Slack or Telegram, picks skills, and starts your agent. -Zero to running in under 60 seconds. - -**Secure by Default** - -Forge is designed for safe execution: +- **60-second setup** — `forge init` wizard configures provider, keys, channels, and skills +- **Secure by default** — outbound-only connections, egress allowlists, encrypted secrets, no public listeners +- **Portable** — same agent runs locally, in Docker, Kubernetes, or inside [Initializ Command](https://initializ.ai) +- **Observable** — structured NDJSON audit logs with correlation IDs for every action +- **Extensible** — add skills, tools, channels, and LLM providers without changing core code -* Does NOT create public tunnels -* Does NOT expose webhooks automatically -* Uses outbound-only connections (Slack Socket Mode, Telegram polling) -* Enforces outbound domain allowlists at both build-time and runtime, including subprocess HTTP via a local egress proxy -* Encrypts secrets at rest (AES-256-GCM) with per-agent isolation -* Signs build artifacts (Ed25519) for supply chain integrity -* Supports restricted network profiles with audit logging - -No accidental exposure. No hidden listeners. - ---- - -## Get Started in 60 Seconds +## Quick Start ```bash # Install -curl -sSL https://github.com/initializ/forge/releases/latest/download/forge-$(uname -s)-$(uname -m).tar.gz | tar xz -sudo mv forge /usr/local/bin/ - -# Initialize a new agent (interactive wizard) -forge init my-agent - -# Run locally -cd my-agent && forge run - -# Run with Telegram -forge run --with telegram -``` +brew install initializ/tap/forge # or download binary from GitHub Releases -The `forge init` wizard walks you through model provider, API key, fallback providers, tools, skills, and channel setup. Use `--non-interactive` with flags for scripted setups. +# Create and run an agent +forge init my-agent && cd my-agent && forge run ---- - -## Install - -### macOS (Homebrew) -```bash -brew install initializ/tap/forge -``` - -### Linux / macOS (binary) -```bash -curl -sSL https://github.com/initializ/forge/releases/latest/download/forge-$(uname -s)-$(uname -m).tar.gz | tar xz -sudo mv forge /usr/local/bin/ -``` - -### Windows - -Download the latest `.zip` from [GitHub Releases](https://github.com/initializ/forge/releases/latest) and add to your PATH. - -### Verify -```bash -forge --version +# Connect to Slack +forge run --with slack ``` ---- +See [Quick Start](docs/quickstart.md) for the full walkthrough, or [Installation](docs/installation.md) for all methods. ## How It Works @@ -98,1249 +39,74 @@ SKILL.md --> Parse --> Discover tools/requirements --> Compile AgentSpec (tool calling + memory + cron) ``` -1. You write a `SKILL.md` that describes what the agent can do -2. Forge parses the skill definitions and optional YAML frontmatter (binary deps, env vars) -3. The build pipeline discovers tools, resolves egress domains, and compiles an `AgentSpec` -4. Security policies (egress allowlists, capability bundles) are applied -5. Build artifacts are checksummed and optionally signed (Ed25519) -6. At runtime, encrypted secrets are decrypted and the LLM-powered tool-calling loop executes with session persistence, memory, and a cron scheduler for recurring tasks - ---- - -## Skills - -Skills are defined in Markdown with optional YAML frontmatter for requirements: - -```markdown ---- -name: weather -description: Weather data skill -metadata: - forge: - requires: - bins: - - curl - env: - required: [] - one_of: [] - optional: [] ---- -## Tool: weather_current - -Get current weather for a location. - -**Input:** location (string) - City name or coordinates -**Output:** Current temperature, conditions, humidity, and wind speed - -## Tool: weather_forecast - -Get weather forecast for a location. - -**Input:** location (string), days (integer: 1-7) -**Output:** Daily forecast with high/low temperatures and conditions -``` - -Each `## Tool:` heading defines a tool the agent can call. The frontmatter declares binary dependencies and environment variable requirements. Skills compile into JSON artifacts and prompt text during `forge build`. - -### Skill Registry - -Forge ships with a built-in skill registry. Add skills to your project with a single command: - -```bash -# Add a skill from the registry -forge skills add tavily-research - -# Validate skill requirements -forge skills validate - -# Audit skill security -forge skills audit --embedded -``` - -`forge skills add` copies the skill's SKILL.md and any associated scripts into your project's `skills/` directory. It validates binary and environment requirements, checks for existing values in your environment, `.env` file, and encrypted secrets, and prompts only for truly missing values with a suggestion to use `forge secrets set` for sensitive keys. - -### Skills as First-Class Tools - -Script-backed skills are automatically registered as **first-class LLM tools** at runtime. When a skill has scripts in `skills/scripts/`, Forge: - -1. Parses the skill's SKILL.md for tool definitions, descriptions, and input schemas -2. Creates a named tool for each `## Tool:` entry (e.g., `tavily_research` becomes a tool the LLM can call directly) -3. Executes the skill's shell script with JSON input when the LLM invokes it - -This means the LLM sees skill tools alongside builtins like `web_search` and `http_request` — no generic `cli_execute` indirection needed. - -For skills **without** scripts (binary-backed skills like `k8s-incident-triage`), Forge injects the full skill instructions into the system prompt. The complete SKILL.md body — including triage steps, detection heuristics, output structure, and safety constraints — is included inline so the LLM follows the skill protocol without needing an extra tool call. Skills are invoked via `cli_execute` with the declared binary dependencies. - -``` -┌─────────────────────────────────────────────────┐ -│ LLM Tool Registry │ -├─────────────────┬───────────────────────────────┤ -│ Builtins │ web_search, http_request │ -│ Skill Tools │ tavily_research, ... │ ← auto-registered from scripts -│ read_skill │ load any SKILL.md on demand │ -│ cli_execute │ run approved binaries │ -├─────────────────┴───────────────────────────────┤ -│ System Prompt: full skill instructions inline │ ← binary-backed skills -└─────────────────────────────────────────────────┘ -``` - -### Skill Execution Security - -Skill scripts run in a restricted environment via `SkillCommandExecutor`: - -- **Isolated environment**: Only `PATH`, `HOME`, and explicitly declared env vars are passed through -- **Configurable timeout**: Each skill declares a `timeout_hint` in its YAML frontmatter (e.g., 300s for research) -- **No shell execution**: Scripts run via `bash