md-files

KO | EN

gitlite — search

#rust #golang #developer-tools #github #gemini #rag #security #privacy #typescript #chatgpt

(★ 9)

my own instructions, skills, hooks and agents I have made for my own use in AI assisted development, now made into the plugin "Forge"

File Explorer

ZIP Download

- - marketplace.json
- marketplace.json
- - 0001-research-stacked-change-practice.md
  - 0002-build-stack-engine.md
  - 0003-add-stack-skills-and-commands.md
  - 0004-integrate-docs-catalog-installers.md
  - 0005-verify-and-release-forge-3.md
  - 0006-capability-ir-v2.md
  - 0007-projection-renderer.md
  - 0008-adapter-contract-tests.md
  - 0009-compiler-gates-docs.md
  - 0010-semantic-capability-diff.md
  - 0011-capability-schema-migration.md
  - 0012-derived-release-surfaces.md
  - 0013-runtime-event-store.md
  - 0014-runtime-outbox-inbox.md
  - 0015-research-runtime-roadmap.md
  - 0016-runtime-heartbeats-fencing.md
  - 0017-runtime-checkpoint-recovery.md
  - 0018-runtime-lineage-receipts.md
  - 0019-runtime-human-waits.md
  - 0020-portable-backend-conformance.md
  - 0021-workflow-definition-versioning.md
  - 0022-signed-trace-provenance.md
  - 0023-distributed-watch-recovery.md
  - 0024-deterministic-chaos-shrinking.md
  - 0025-adaptive-routing-foundation.md
  - 0026-gh-aw-compiler.md
  - 0027-gh-aw-runtime-bridge.md
  - 0028-gh-aw-provider-worker.md
  - 0029-reviewed-adaptive-routing-rollout.md
  - 0030-gh-aw-dispatch-reconciliation.md
  - 0031-native-gh-aw-compiler-gate.md
  - 0032-native-gh-aw-reproducibility.md
  - 0033-native-gh-aw-admission.md
  - 0034-native-gh-aw-preflight.md
  - 0035-native-gh-aw-provider-admission.md
  - 0036-native-gh-aw-worker-handoff.md
  - 0037-native-gh-aw-lease-supervision.md
  - 0038-openai-agent-plugin-compatibility-audit.md
  - 0039-codex-marketplace-contract-gate.md
  - 0040-openai-skills-submission-evidence.md
  - 0041-evaluate-optional-openai-mcp-ui.md
  - 0042-constellation-integration.md
  - 0043-installed-candidate-replay-evidence.md
  - 0044-mcp-2026-07-28-tasks-adapter.md
  - 0045-dsse-slsa-v1-2-attestation-verification.md
  - 0046-trajectory-agentic-security-evals.md
  - 0047-agent-identity-delegated-authority.md
  - 0048-host-authenticated-admission.md
  - 0049-a2a-agent-card-contract.md
  - 0050-a2a-task-handoff.md
  - 0051-a2a-stream-evidence.md
  - 0052-gh-aw-runtime-profile-admission.md
  - 0053-mcp-task-request-admission.md
  - README.md
- - package-lock.json
  - package.json
- - bug_report.md
  - new_component.md
- - ci.yml
  - release.yml
- dependabot.yml
- PULL_REQUEST_TEMPLATE.md
- requirements-ci.txt
- action-envelope.schema.json
- bundles.json
- capabilities.json
- capabilities.schema.json
- catalog.json
- doctor-profiles.json
- gh-aw-workflows.json
- host-adapter.schema.json
- host-capabilities.json
- policy-decision.schema.json
- policy.schema.json
- receipts.schema.json
- release-attestation.schema.json
- runtime-a2a-card.schema.json
- runtime-a2a-stream.schema.json
- runtime-a2a-task.schema.json
- runtime-authority.schema.json
- runtime-backend-evidence.schema.json
- runtime-backend.schema.json
- runtime-chaos-corpus.schema.json
- runtime-chaos-result.schema.json
- runtime-chaos-schedule.schema.json
- runtime-checkpoints.schema.json
- runtime-compatibility.schema.json
- runtime-conformance.schema.json
- runtime-definitions.schema.json
- runtime-distributed.schema.json
- runtime-events.schema.json
- runtime-gh-aw-admission.schema.json
- runtime-gh-aw-episode.schema.json
- runtime-gh-aw-firewall.schema.json
- runtime-gh-aw-provider-request.schema.json
- runtime-gh-aw-worker-handoff.schema.json
- runtime-gh-aw.schema.json
- runtime-host-admission.schema.json
- runtime-inbox.schema.json
- runtime-lease-events.schema.json
- runtime-lineage.schema.json
- runtime-mcp-tasks.schema.json
- runtime-migrations.schema.json
- runtime-outbox.schema.json
- runtime-provenance.schema.json
- runtime-receipts.schema.json
- runtime-restore.schema.json
- runtime-routing-decision.schema.json
- runtime-routing-policy.schema.json
- runtime-routing-replay.schema.json
- runtime-routing-rollout.schema.json
- runtime-state.schema.json
- runtime-waits.schema.json
- scenario-results.schema.json
- scenarios.schema.json
- trajectory-evals.schema.json
- workflows.json
- a2a-stream.md
- a2a-task.md
- a2a.md
- architecture.md
- authority.md
- bundles-and-workflows.md
- capability-ir.md
- ci-and-headless.md
- competitive-audit.md
- conformance.md
- constellation-integration.md
- design-rationale.md
- frontier-roadmap.md
- getting-started.md
- gh-aw.md
- github-native-stacks.md
- github-task-ledger.md
- marketplace-readiness.md
- openai-agent-plugin-submission.md
- openai-agent-plugins.md
- openai-mcp-ui-decision.md
- opencode.md
- policy-plane.md
- privacy.md
- provenance.md
- quality-bar.md
- receipts.md
- release-provenance.md
- routing.md
- runtime-roadmap.md
- runtime.md
- stacked-changes.md
- support.md
- terms.md
- trajectory-evals.md
- usage-patterns.md
- cases.jsonl
- README.md
- run.py
- run_scenarios.py
- scenarios.jsonl
- - go.md
  - python.md
  - typescript.md
- - CLAUDE.md.template
  - global-CLAUDE.md
- engineering-principles.md
- README.md
- .mcp.json.example
- README.md
- default.json
- gh-aw.json
- github-mutation.json
- production.json
- release.json
- review.json
- build_openai_submission_evidence.py
- build_release.py
- compile_capabilities.py
- diff_capabilities.py
- forge-a2a-card.py
- forge-a2a-stream.py
- forge-a2a-task.py
- forge-attestation.py
- forge-authority.py
- forge-chaos.py
- forge-doctor.py
- forge-gh-aw-provider.py
- forge-gh-aw-runtime.py
- forge-gh-aw.py
- forge-host-admission.py
- forge-lineage.py
- forge-mcp-tasks.py
- forge-policy.py
- forge-provenance.py
- forge-receipts.py
- forge-routing.py
- forge-runtime.py
- forge-stack-merge.py
- forge-stack-sync.py
- forge-tasks.py
- forge-trajectory-evals.py
- generate_catalog.py
- install-opencode.sh
- install.sh
- local-release-check.sh
- marketplace-smoke.sh
- migrate_capabilities.py
- render_capabilities.py
- validate.sh
- validate_codex_plugin.py
- verify_release.py
- README.md
- settings.json.example
- forge-statusline.sh
- README.md
- README.md
- test_capability_diff_migration.py
- test_capability_ir.py
- test_capability_renderer.py
- test_codex_plugin_validation.py
- test_forge_a2a_card.py
- test_forge_a2a_stream.py
- test_forge_a2a_task.py
- test_forge_attestation.py
- test_forge_authority.py
- test_forge_backends.py
- test_forge_chaos.py
- test_forge_definitions.py
- test_forge_doctor.py
- test_forge_gh_aw.py
- test_forge_gh_aw_firewall.py
- test_forge_gh_aw_provider.py
- test_forge_gh_aw_runtime.py
- test_forge_host_admission.py
- test_forge_lineage.py
- test_forge_mcp_tasks.py
- test_forge_policy.py
- test_forge_provenance.py
- test_forge_receipts.py
- test_forge_release.py
- test_forge_routing.py
- test_forge_runtime.py
- test_forge_scenarios.py
- test_forge_stack.py
- test_forge_stack_merge.py
- test_forge_stack_sync.py
- test_forge_tasks.py
- test_forge_trajectory.py
- test_hooks.py
- test_marketplace_readiness.py
- test_openai_submission_evidence.py
- test_opencode_compatibility.py
- test_release_surface_renderer.py
- - profiles.json
- AGENTS.md
- install.sh
- README.md
.editorconfig
.gitignore
.markdownlint.yaml
AGENTS.md
CATALOG.md
CHANGELOG.md
CODEOWNERS
CONTRIBUTING.md
justfile
LICENSE
opencode.json
README.md
SECURITY.md
SUPPORT.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**An enterprise-grade Claude Code, Codex, and OpenCode toolkit — specialized agents,
progressive-disclosure skills, orchestration loops, slash commands, and safety hooks that
maximize the efficacy of LLMs in software engineering.**

[![CI](https://github.com/AlisinaDevelo/md-files/actions/workflows/ci.yml/badge.svg)](https://github.com/AlisinaDevelo/md-files/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)](https://docs.claude.com/en/docs/claude-code)
[![Agents](https://img.shields.io/badge/agents-20-8b5cf6.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/plugins/forge/agents/)
[![Skills](https://img.shields.io/badge/skills-25-06b6d4.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/plugins/forge/skills/)
[![Commands](https://img.shields.io/badge/commands-22-22c55e.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/plugins/forge/commands/)
[![Tests](https://img.shields.io/badge/tests-421%20passing-success.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/tests/)
[![Prompt evals](https://img.shields.io/badge/prompt%20evals-333%2F334%20checks-success.svg)](https://raw.githubusercontent.com/AlisinaDevelo/md-files/main/evals/)

</div>

---

Forge is a curated, batteries-included configuration for [Claude Code](https://docs.claude.com/en/docs/claude-code),
[Codex](https://github.com/openai/codex), and [OpenCode](https://opencode.ai). It packages the patterns that make an AI coding agent
genuinely effective — clear role definitions, disciplined methodologies, task ledgers,
model routing, the right tools for each job, and guardrails that keep it safe — into one
installable toolkit. Every artifact is plain Markdown or a small, auditable script: no
build step, no magic, nothing hidden from you.

## Table of contents

- [Why Forge](#why-forge)
- [Install](#install)
- [What's inside](#whats-inside)
  - [Agents](#agents)
  - [Skills](#skills)
  - [Commands](#commands)
  - [Hooks](#hooks)
  - [Output styles, status line & settings](#output-styles-status-line--settings)
  - [Instructions & MCP](#instructions--mcp)
  - [Evidence — evals & tests](#evidence--evals--tests)
- [Release provenance](#release-provenance)
- [How the pieces fit](#how-the-pieces-fit)
- [Repository layout](#repository-layout)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

## Why Forge

LLM coding agents are only as good as the scaffolding around them. The same model
produces dramatically different results depending on whether it has a sharp role, a
proven method, scoped tools, and guardrails. Forge encodes that scaffolding:

- **Specialists, not a generalist.** Twenty agents each with a focused role, a concrete
  methodology, scoped tools, and a defined output format — a reviewer that thinks like a
  reviewer, a debugger that finds root causes, an auditor that traces taint to sinks.
- **Orchestration for big work.** Plan at Opus/Fable, decompose into a task ledger, route
  implementation to Sonnet, fan out mechanical work to Haiku, and iterate to verified done.
- **Durable local execution.** SQLite/WAL run history, idempotent lifecycle events,
  tamper-evident replay, digest-pinned workflow code/schema and worker definitions, fail-closed
  compatibility gates for replay, migration, restore, and effect retry, checkpointed recovery,
  offline lineage and signed provenance verification, and a strict
  separation between execution state, task planning, and privacy-safe receipts give long-running
  orchestration a recoverable foundation. The portable backend facade also models etcd-first
  distributed revisions, watch delivery, verified snapshots, and compaction recovery without
  treating provider metadata as canonical history.
- **Stacked delivery, now native.** Design and verify dependent PRs with a portable stack
  manifest, default to GitHub's first-party `gh stack`, or adapt the same safety protocol
  to vanilla GitHub, Graphite, Aviator, Sapling, and classic ghstack.
- **Authorization before effects.** Declarative policy profiles bind exact actions to
  principals, resources, revisions, and one-use approvals, with staged previews and
  committed-effect receipts for GitHub mutations, releases, and production workflows.
- **Discoverability without bloat.** `/forge`, [CATALOG.md](CATALOG.md), bundles, and
  workflows route work to the smallest useful capability instead of dumping every skill
  into context.
- **Canonical capability contract.** A body-aware v2 graph records component identity,
  instructions, tools, permissions, resources, eval links, and explicit Claude/Codex/
  Agent Skills projections so host compatibility is reviewable and drift fails the gate.
  See
  [Capability IR](docs/capability-ir.md).
- **Methodology on tap.** Twenty-five skills inject battle-tested practices — TDD,
  root-cause debugging, threat modeling, safe migrations, orchestration, catalogs, task
  ledgers, and solve loops — exactly when the situation calls for them.
- **One-keystroke workflows.** Twenty-two slash commands wrap the everyday loop: forge,
  review, test, debug, plan, commit, PR, orchestrate, tasks, solve-loop, stack, stack-review.
- **Safety by default.** Lifecycle hooks block catastrophic commands and secret leaks,
  auto-format edits, inject repo context at session start, and notify you on completion —
  deterministically, without relying on the model to remember.
- **Proven, not asserted.** A real eval harness scores prompts and high-risk behavior
  contracts (333/334 deterministic checks, one warning, plus cross-host scenarios and an opt-in
  LLM judge); 421 tests cover safety hooks, task sync, receipts, durable runtime replay, external effect
  delivery, doctor, policy,
  stacks, marketplace readiness, capability graph, rendering, semantic evidence, and conformance. Run
  them yourself — `just check`.
- **Auditable & self-validating.** Read every prompt and script. CI validates structure,
  runs the tests, and scores the evals on every push. GitHub-backed task ledgers add stable
  issue identity, native task graphs, conflict stops, and resumable evidence.
- **GitHub-native workflow bridge.** A pinned `gh-aw` adapter projects Forge orchestration
  into deterministic workflow sources, read-only agent jobs, staged safe outputs, and
  source-to-lock drift checks. Its optional provider worker adds fenced leases, exact one-use
  approvals, account verification, idempotent recovery, and reference-only GitHub receipts
  without committing credentials.

## Install

**Claude Code plugin (recommended — includes agents, commands, and hooks):**

```bash
# In Claude Code:
/plugin marketplace add AlisinaDevelo/md-files
/plugin install forge@forge
```

**Codex plugin (skills and orchestration methods):**

```bash
codex plugin marketplace add AlisinaDevelo/md-files
codex plugin add forge@forge
```

**OpenCode (Agent Skills and project instructions):**

```bash
git clone https://github.com/AlisinaDevelo/md-files.git
cd md-files
./scripts/install-opencode.sh --copy
```

See [OpenCode support](docs/opencode.md) for copy, symlink, verification, and host-boundary details.

Repository marketplace installation is available for Claude Code and Codex, while OpenCode
uses the Agent Skills installer. Forge has not been submitted to the public Claude or Codex
directories; see [Marketplace readiness](docs/marketplace-readiness.md) for the dated
publication state, publisher surfaces, and submission evidence.

**As user-level symlinks (Claude agents, skills, commands):**

```bash
git clone https://github.com/AlisinaDevelo/md-files.git && cd md-files
./scripts/install.sh        # or --copy / --dry-run
```

**As `.agents` skills (Codex, Zed, and OpenCode):**

```bash
git clone https://github.com/AlisinaDevelo/md-files.git && cd md-files/zed
./install.sh                # installs Forge skills into ~/.agents/skills
```

**Cherry-pick:** everything is plain Markdown — copy any file into your own `~/.claude/`
or project `.claude/`. See [docs/getting-started.md](docs/getting-started.md) for details.

## What's inside

### Agents

Delegated, autonomous specialists with their own context and scoped tools.

| Agent | Role |
|-------|------|
| [`code-reviewer`](plugins/forge/agents/code-reviewer.md) | Severity-ranked review for correctness, security, and maintainability |
| [`debugger`](plugins/forge/agents/debugger.md) | Hypothesis-driven root-cause diagnosis |
| [`security-auditor`](plugins/forge/agents/security-auditor.md) | Defensive vulnerability review (OWASP/CWE, taint→sink) |
| [`test-engineer`](plugins/forge/agents/test-engineer.md) | Behavior-focused tests that reduce real risk |
| [`architect`](plugins/forge/agents/architect.md) | Implementation plans and architectural trade-offs |
| [`refactoring-specialist`](plugins/forge/agents/refactoring-specialist.md) | Behavior-preserving structural improvement |
| [`performance-optimizer`](plugins/forge/agents/performance-optimizer.md) | Measure-first bottleneck diagnosis and fixes |
| [`database-expert`](plugins/forge/agents/database-expert.md) | Schema design, query tuning, safe migrations |
| [`api-designer`](plugins/forge/agents/api-designer.md) | Consistent, evolvable API contracts |
| [`frontend-specialist`](plugins/forge/agents/frontend-specialist.md) | Component architecture, state, render performance |
| [`accessibility-auditor`](plugins/forge/agents/accessibility-auditor.md) | WCAG audit and remediation |
| [`dependency-auditor`](plugins/forge/agents/dependency-auditor.md) | CVEs, license risk, safe upgrade planning |
| [`devops-engineer`](plugins/forge/agents/devops-engineer.md) | CI/CD, containers, IaC, safe deploys |
| [`docs-writer`](plugins/forge/agents/docs-writer.md) | Accurate, example-driven documentation |
| [`incident-responder`](plugins/forge/agents/incident-responder.md) | Triage, mitigate, then root-cause + postmortem |
| [`code-archaeologist`](plugins/forge/agents/code-archaeologist.md) | Understand unfamiliar/legacy code before changing it |
| [`migration-specialist`](plugins/forge/agents/migration-specialist.md) | Incremental, reversible framework/library/API migrations |
| [`data-engineer`](plugins/forge/agents/data-engineer.md) | Data pipelines, ETL/ELT, warehouse modeling, data quality |
| [`sre`](plugins/forge/agents/sre.md) | SLOs, error budgets, capacity, toil reduction, reliability |
| [`tech-lead`](plugins/forge/agents/tech-lead.md) | Orchestrates large tasks across the specialists |

### Skills

Methodologies and references injected into the current conversation when the situation
matches. Several use **progressive disclosure** — a lean `SKILL.md` plus deeper reference
files loaded only when needed.

| Skill | When it fires |
|-------|---------------|
| [`test-driven-development`](plugins/forge/skills/test-driven-development/) | Implementing test-first (red-green-refactor) |
| [`root-cause-debugging`](plugins/forge/skills/root-cause-debugging/) | Diagnosing a bug or failure |
| [`code-review-rubric`](plugins/forge/skills/code-review-rubric/) | Reviewing code (+ full checklist) |
| [`refactoring-catalog`](plugins/forge/skills/refactoring-catalog/) | Improving structure (+ smell→fix catalog) |
| [`conventional-commits`](plugins/forge/skills/conventional-commits/) | Writing commit messages |
| [`pull-request-authoring`](plugins/forge/skills/pull-request-authoring/) | Opening a reviewable PR |
| [`api-design`](plugins/forge/skills/api-design/) | Designing or reviewing an API |
| [`threat-modeling`](plugins/forge/skills/threat-modeling/) | Security design review (STRIDE) |
| [`safe-database-migrations`](plugins/forge/skills/safe-database-migrations/) | Schema changes on live data |
| [`performance-profiling`](plugins/forge/skills/performance-profiling/) | Investigating performance |
| [`observability`](plugins/forge/skills/observability/) | Adding logs/metrics/traces |
| [`technical-writing`](plugins/forge/skills/technical-writing/) | Writing developer docs |
| [`git-workflow`](plugins/forge/skills/git-workflow/) | Branching, rebasing, conflicts, recovery, bisect |
| [`error-handling`](plugins/forge/skills/error-handling/) | Designing robust failure paths |
| [`feature-flags`](plugins/forge/skills/feature-flags/) | Gating, progressive rollout, and flag cleanup |
| [`caching-strategies`](plugins/forge/skills/caching-strategies/) | Cache patterns, TTLs, invalidation, stampedes |
| [`concurrency-and-parallelism`](plugins/forge/skills/concurrency-and-parallelism/) | Races, locks, async, idempotency |
| [`prompt-engineering`](plugins/forge/skills/prompt-engineering/) | Authoring agents/skills/commands (+ patterns) |
| [`forge-catalog`](plugins/forge/skills/forge-catalog/) | Choose the right Forge command, agent, skill, bundle, or workflow |
| [`orchestration`](plugins/forge/skills/orchestration/) | Multi-model planning, delegation, integration, and verification |
| [`task-ledger`](plugins/forge/skills/task-ledger/) | Jira/GitHub-issue-like local tasks with status, deps, agent, and model |
| [`iterate-to-done`](plugins/forge/skills/iterate-to-done/) | Solve-loop discipline for draining a ledger until done or blocked |
| [`stacked-changes`](plugins/forge/skills/stacked-changes/) | GitHub-native and vendor-neutral stacked PR design, review, native reconciliation, restack, recovery, and landing |
| [`doctor`](plugins/forge/skills/doctor/) | Read-only host, capability, repository-policy, and merge-readiness diagnostics |
| [`policy`](plugins/forge/skills/policy/) | Declarative authorization, staged previews, scoped approvals, and decision receipts |

### Commands

User-triggered prompt templates with argument and shell injection.

| Command | Does |
|---------|------|
| `/forge` | Choose the right Forge agent, skill, command, bundle, or workflow |
| `/review` | Review the current diff, severity-ranked |
| `/commit` | Draft a Conventional Commit for staged changes |
| `/test` | Write tests matching the repo's harness |
| `/debug` | Root-cause a bug before fixing |
| `/plan` | Step-by-step implementation plan |
| `/refactor` | Behavior-preserving cleanup |
| `/security-scan` | Defensive security review of the diff |
| `/pr` | Draft a PR description from the branch |
| `/optimize` | Measure-first performance fix |
| `/explain` | Explain a file, symbol, or system |
| `/docs` | Write docs grounded in the code |
| `/tidy` | Remove cruft from the diff, behavior-preserving |
| `/changelog` | Draft a changelog entry from commits since the last release |
| `/scaffold` | Scaffold a new module/component matching repo conventions |
| `/orchestrate` | Plan a big goal, create a task ledger, route work by agent/model, and drive it to done |
| `/tasks` | Create, list, update, or GitHub-sync the task ledger |
| `/solve-loop` | Drain ready ledger tasks with verify-before-done discipline |
| `/stack` | Plan, inspect, submit, reconcile, restack, repair, or land dependent pull requests |
| `/stack-review` | Review every stack layer bottom-up against its immediate parent |
| `/doctor` | Run the read-only Forge capability and merge-readiness preflight |
| `/policy` | Evaluate policy, stage effects, issue approvals, authorize, and record outcomes |

### Hooks

Deterministic guardrails the harness runs on lifecycle events — no model memory required.

| Hook | Event | Effect |
|------|-------|--------|
| [`session-context`](plugins/forge/hooks/scripts/session-context.py) | SessionStart | Injects current branch, ahead/behind, dirty count, and recent commits as context |
| [`guard-bash`](plugins/forge/hooks/scripts/guard-bash.py) | PreToolUse(Bash) | Blocks catastrophic commands (`rm -rf /`, force-push to main, fork bombs) |
| [`scan-secrets`](plugins/forge/hooks/scripts/scan-secrets.py) | PreToolUse(Write/Edit) | Blocks writing credentials into files |
| [`format-file`](plugins/forge/hooks/scripts/format-file.sh) | PostToolUse(Write/Edit) | Auto-formats edited files with the installed formatter |
| [`notify`](plugins/forge/hooks/scripts/notify.sh) | Stop | Desktop notification when a turn finishes |

### Output styles, status line & settings

- [`output-styles/`](plugins/forge/output-styles/) — selectable system-prompt modes:
  **Concise Engineer** (answer-first, no preamble) and **Mentor** (teaches the *why* as it
  works). Ship with the plugin; pick one via `/config`.
- [`statusline/`](statusline/) — a status line showing model · dir · git · context% · cost.
- [`settings/`](settings/) — example `settings.json` (permission allowlist, deny rules for
  secrets, status line, output style) to pair with the plugin.

### Instructions & MCP

- [`instructions/`](instructions/) — a `CLAUDE.md` template library, stack-agnostic
  [engineering principles](instructions/engineering-principles.md), and language snippets
  (TypeScript, Python, Go).
- [`mcp/`](mcp/) — example Model Context Protocol server configs with least-privilege
  guidance.

### Evidence — evals & tests

- [`evals/`](evals/) — deterministic prompt-quality and behavior-contract checks, shared
  cross-host scenarios, and an opt-in LLM-judge eval that scores agents against real tasks.
- [`tests/`](tests/) — pytest cases covering safety hooks, task sync, receipts, durable
  runtime replay, external effect delivery, doctor, stacks, and conformance. `just check`
  runs it all.

## Release provenance

Tagged releases publish deterministic Claude, Codex, and `.agents` bundles with SHA-256
manifests, SPDX SBOMs, GitHub artifact attestations, and an offline verifier. See
[release provenance](docs/release-provenance.md) for consumer verification and the
threat model.

## How the pieces fit

```mermaid
flowchart LR
  goal["big goal\n/orchestrate"] --> ledger["task ledger\n/tasks"]
  ledger --> route["route by agent + model\nOpus/Fable · Sonnet · Haiku"]
  route --> loop["solve loop\n/solve-loop"]
  loop --> done["verified done"]
  ledger --> topology{"one PR or stack?"}
  topology --> stack["stack graph\n/stack"]
  stack --> stackreview["incremental review\n/stack-review"]
  stackreview --> done

plan["plan\narchitect / /plan"] --> impl[implement]
  impl --> review["review\ncode-reviewer / /review"]
  review --> test["test\ntest-engineer / /test"]
  test --> debug["debug\ndebugger / /debug"]
  debug --> ship["ship\n/commit · /pr"]

guard(["guardrails — always on\nguard-bash · scan-secrets · format-file · notify"])
  guard -. wraps .-> impl
  guard -. wraps .-> review
  guard -. wraps .-> debug
  guard -. wraps .-> ship
```

Agents go deep on focused jobs; skills supply the method; commands trigger the loop;
hooks keep it safe. For big tasks, the main conversation acts as the conductor so it can
spawn specialists in parallel; the ledger keeps the run honest. See
[docs/usage-patterns.md](docs/usage-patterns.md).

## Repository layout

```text
.claude-plugin/        Claude Code marketplace manifest
.agents/plugins/       Codex marketplace manifest
data/                  generated catalog, capability graph, bundles, and workflow metadata
plugins/forge/         the Forge plugin
  .claude-plugin/        plugin manifest
  .codex-plugin/         Codex plugin manifest
  agents/                20 specialist subagents
  skills/                25 progressive-disclosure skills
  commands/              22 slash commands
  hooks/                 5 lifecycle hooks (session-context, guard, secrets, format, notify)
  output-styles/         selectable system-prompt modes
instructions/          CLAUDE.md templates, principles, language guides
mcp/                   example MCP server configs
statusline/            status line script
settings/              example settings.json
evals/                 prompt eval harness, shared scenarios, and result evidence
tests/                 runnable hook, task-ledger, receipt, doctor, stack, and conformance tests
docs/                  getting started, usage, architecture, rationale, CI
scripts/               validation, installation, release, and marketplace checks
.github/               CI, issue/PR templates, CODEOWNERS, dependabot
```

## Documentation

- [Getting started](docs/getting-started.md) — install options and first steps
- [Usage patterns](docs/usage-patterns.md) — how the components combine in real workflows
- [Bundles & workflows](docs/bundles-and-workflows.md) — focused capability sets and ordered playbooks
- [Quality bar](docs/quality-bar.md) — validation and safety standards for Forge components
- [Competitive audit](docs/competitive-audit.md) — what Forge borrows from larger skill libraries
- [Frontier roadmap](docs/frontier-roadmap.md) — research-backed interoperability, identity,
  evaluation, release evidence, and connected-execution priorities
- [Stacked changes](docs/stacked-changes.md) — GitHub-native stacks, provider adapters,
  safety model, review flow, CI, and recovery
- [GitHub native stacks](docs/github-native-stacks.md) — remote inspect/import, SHA-guarded
  reconciliation, divergence classes, mutation authority, and preview fallback
- [Policy plane](docs/policy-plane.md) — action envelopes, profiles, approvals, staged
  previews, adapter integration, and privacy-safe decision evidence
- [Cross-host conformance](docs/conformance.md) — shared scenarios, host adapters, live
  evidence, result schemas, and release gates
- [Release provenance](docs/release-provenance.md) — deterministic bundles, SBOMs,
  attestations, offline verification, and threat model
- [Marketplace readiness](docs/marketplace-readiness.md) — honest directory status,
  publisher surfaces, asset policy, and submission smoke-test matrix
- [OpenAI Agent Plugins compatibility](docs/openai-agent-plugins.md) — current universal
  plugin contract, Forge audit, submission boundary, and staged compatibility plan
- [OpenAI submission packet](docs/openai-agent-plugin-submission.md) — reproducible candidate
  archive evidence, five positive/three negative cases, and the external publication boundary
- [Capability IR](docs/capability-ir.md) — body-aware graph, deterministic host renderer,
  adapter contract, migration workflow, and current compiler boundary
- [Durable runtime](docs/runtime.md) — local SQLite/WAL history, deterministic replay,
  transactional outbox/inbox effects, generation-fenced heartbeats, lease evidence,
  checkpointed recovery, human-input waits, signals, MCP Tasks projection, reviewed
  migrations, offline lineage verification, signed trace/provenance evidence, idempotency,
  hash-chain verification, and explicit at-least-once boundaries
- [Runtime provenance](docs/provenance.md) — signed trace correlation, privacy defaults,
  offline trust verification, key rotation, retention, and incident response
- [GitHub Agentic Workflows](docs/gh-aw.md) — pinned gh-aw compilation, read-only agents,
  staged safe outputs, policy evidence, native lock verification, and durable episode correlation
- [Architecture](docs/architecture.md) — how the repo is organized and why
- [Design rationale](docs/design-rationale.md) — the decisions and trade-offs behind Forge
- [CI & headless usage](docs/ci-and-headless.md) — run Forge in pipelines and automated review
- [Evals](evals/) — the evidence layer · [Tests](tests/) — hook test suite
- [Contributing](CONTRIBUTING.md) — add an agent, skill, command, or hook
- [Changelog](CHANGELOG.md)

## Contributing

Contributions are welcome — new agents, skills, commands, and hooks, or improvements to
existing ones. Run `./scripts/validate.sh` before opening a PR. See
[CONTRIBUTING.md](CONTRIBUTING.md) for the conventions and the quality bar.

## License

md-files

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

md-files

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README