Forge is a prompt-only repository — no application code, no runtime, no dependencies. It contains Agent Skills prompt files (SKILL.md) that teach compatible agents how to execute a structured development workflow with pluggable issue tracking (GitHub, markdown plan/ folder, or user-configured provider).
forge/
├── skills/
│ ├── forge-setup-project/
│ │ ├── SKILL.md # Step 0: Context infrastructure setup/audit
│ │ └── references/ # Progressive disclosure: templates, output format
│ ├── forge-shape/ # Optional: Shape ideas into plans before issue creation
│ │ ├── SKILL.md
│ │ └── references/shaping-methodology.md # One-at-a-time questioning philosophy
│ ├── _shared/ # Cross-skill references (see coding-guidelines.md)
│ │ ├── issue-operations.md # Provider detection and Issue CRUD
│ │ ├── plan-folder-spec.md # Markdown issue tracker provider spec
│ │ ├── review-delegation.md # Lean review flow: inline vs fresh-context passes
│ │ ├── review-rubric.md # P0–P3 severity taxonomy
│ │ ├── review-dimensions.md # Lean review checklists: default pass + optional deep passes
│ │ ├── vertical-slicing.md # Thin end-to-end slicing philosophy
│ │ ├── phase-execution.md # Pre-flight, per-phase loop, phase gates
│ │ ├── pattern-audit.md # Pattern consistency audit checklist
│ │ ├── deep-modules.md # Module depth audit checklist
│ │ ├── barrel-imports.md # Import structure discipline
│ │ └── roles/ # Cross-skill personas: forge-reviewer, forge-scout
│ ├── forge-create-issue/
│ │ ├── SKILL.md # Step 1: Plan and create Issues (provider-agnostic)
│ │ └── references/ # AFK/HITL classification
│ ├── forge-implement/SKILL.md # Step 2: Implement from Issue, plan, or description
│ ├── forge-reflect/SKILL.md # Step 3: Self-review changes (PR, branch, or uncommitted)
│ ├── forge-address-pr-feedback/SKILL.md # Step 4: Address PR review comments
│ └── forge-ship/SKILL.md # Composite: implement + review in one invocation
├── docs/ # Project documentation
├── AGENTS.md # Canonical agent guidance
├── CLAUDE.md → AGENTS.md # Compatibility symlink
└── README.md # Project overview
The skills form a workflow. Each non-terminal skill references the next step in its "Related Skills" section:
forge-setup-project → [forge-shape →] forge-create-issue → forge-implement → forge-reflect → forge-address-pr-feedback
╰──── forge-ship ────╯
forge-shape is optional — use it when the idea is vague and needs convergent questioning to specify before issue creation.
forge-ship is a composite skill — it executes implement's process and the review flow shared with reflect in a single invocation, with one fresh-context reviewer by default (its session authors the diff, so review always delegates).
- forge-setup-project sets up or audits a project's context infrastructure using a three-tier model:
AGENTS.mdas lean hot memory,docs/as earned warm memory, andspecs/(or equivalent) as cold memory, with signal-to-noise scoring for existing guidance. It also supports migrating legacyCLAUDE.md-first repos to anAGENTS.md-first layout. - forge-shape investigates the codebase, shapes the problem through one-at-a-time questioning — challenging terminology against CONTEXT.md, cross-referencing claims against code, stress-testing with concrete scenarios — until a shared design concept emerges. Updates CONTEXT.md inline as terms are resolved. Optionally explores contrasting approaches if shaping didn't surface one, and produces a plan summary ready for issue creation
- forge-create-issue uses AskUserQuestion to collaboratively scope work, then creates Issues in the project's Issue tracker (GitHub, markdown
plan/folder, or user-configured provider) - forge-implement reads an Issue, plan file, or free-text description, researches the codebase (optionally via blind scout delegation for complex work), plans vertical implementation phases following
_shared/phase-execution.md, and opens a PR - forge-reflect self-reviews changes (PR, branch diff, or uncommitted) inline for tiny low-risk diffs the session didn't author, otherwise using one fresh-context reviewer by default and adding a second focused pass only for high-risk or broad diffs, with a P0-P3 severity rubric
- forge-address-pr-feedback fetches unresolved review threads via GraphQL and addresses each one
- forge-ship executes forge-implement's process, then delegates review to one fresh-context reviewer by default (the session authored the diff) and triages findings with the user
See coding-guidelines.md for the complete reference: YAML frontmatter fields, section order, delegate step conventions, and role file format.
Skills use progressive disclosure: SKILL.md contains core instructions, while templates and detailed reference material live in references/ and load only when needed. Every skill accepts -- <additional context> as the final segment.
LLMs degrade past approximately 100k tokens regardless of the advertised context window. Attention relationships scale quadratically with token count; the further past 100k a session goes, the worse its instruction-following, recall, and reasoning become. The boundary is not a hard threshold — it is a gradual degradation that becomes pronounced enough to act on.
Practitioners call the workable region the smart zone and the degraded region the dumb zone. Forge's design choices respond to this constraint:
| Mechanism | How it responds |
|---|---|
Sub-agent delegation ((delegate) steps) |
Move work into fresh context windows when the parent is approaching the dumb zone |
Fresh-context review (forge-reflect, forge-ship) |
Tiny low-risk diffs stay inline only when the session didn't author them; otherwise one reviewer starts in smart zone by default, and depth is added only when risk justifies it |
Progressive disclosure (references/) |
Load companion philosophy on demand instead of always-loading every skill's full content |
Three-tier context model (AGENTS.md / docs/ / specs) |
Each tier earns its always-loaded cost; cold tier loads only when needed |
| Instruction budget (under ~35 instructions per skill body) | Skills stay lean enough to compose without exceeding the ~150–200 instructions frontier LLMs follow consistently |
Role files (roles/*.md) |
Sub-agents start with focused persona context, not the parent's accumulated history |
The smart-zone constraint is approximate, model-dependent, and changing — but treating it as a real boundary tends to produce more reliable workflows than assuming the advertised context size is the working size. When a skill's design feels like it has too many moving parts to fit in one head, that is also approximately when it has too many tokens to fit in the smart zone.
The instruction-budget figures (~150–200 followed reliably overall, under ~35 per skill) are a related but distinct constraint covered in coding-guidelines.md — they concern how many discrete instructions an LLM follows reliably, separately from how many tokens fit in the smart zone.
| Decision | Choice | Rationale |
|---|---|---|
| Prompt files, not code | SKILL.md | Skills are prompt templates — no runtime needed |
| Conventional commits | Enforced in every skill | Consistent naming across issues, branches, commits, PRs |
| GraphQL for PR threads | Required in address-pr-feedback | REST API doesn't expose isResolved on review threads |
| AskUserQuestion | Used for interactive skills | Structured user input with options, not free-form |
| Pipeline linking | Each skill's "Related Skills" section | Skills reference the next step so users discover the workflow |
| Sub-agent delegation | (delegate) step pattern; context: fork frontmatter available for whole-skill forking |
Fresh context for unbiased review; (delegate) works across runtimes, context: fork is Claude Code's native whole-skill mechanism — unsuitable for skills with interactive steps |
| Skill composition | Composite skills reuse component processes and shared _shared/ modules |
Keeps orchestrators lean; shared modules prevent duplicated step-level instructions from drifting |
| Tool-layer integration | Skills reference external tools by name, not by import | Runtimes and extensions expose delegation/model-selection capabilities; skills use them when available and fall back when not — zero coupling. Runtime-specific agent files or presets are optional local tuning, not part of Forge. When a runtime couples agent names to model/provider selection, push role content, prefer inheriting the parent session configuration over hard-coded agent IDs, use cheap fast models for factual scouting, and prefer cheaper review-capable models for routine review work |
| Reusable roles | Skill-specific: <skill>/roles/*.md; cross-skill: _shared/roles/*.md |
Delegation personas separated from skill body; single-use roles co-locate with the skill, shared roles live in _shared/ |
| Blind research delegation | Scout researches codebase without seeing the Issue | Knowing the goal causes opinions to leak into research — objective facts lead to better planning |
| Vertical implementation phases | Each phase is a thin end-to-end slice, not a horizontal layer | Horizontal plans (all DB, then all services, then all API) produce untestable intermediate states |
| Three-tier context model | Hot (AGENTS.md) / Warm (docs/) / Cold (specs) |
Generic context hurts agent performance — tiered model ensures each doc earns its token cost |
| Compatibility layer | CLAUDE.md symlink to AGENTS.md |
Preserve compatibility without making vendor-specific filenames canonical |
| Push vs pull context loading | Push = embed content in initial prompt; Pull = read on demand via file references | Push when reliability matters more than token economy (review rubric, role definitions); pull for optional philosophy and templates that the agent may not need. Progressive disclosure (references/) is pull by default; delegation prompts should push critical instructions so sub-agents don't skip or misread them |
| Issue tracker abstraction | Provider operations in _shared/issue-operations.md; skills reference it |
Concentrates provider detection and CRUD in one module; skills say "create an Issue" without re-deriving the three-way conditional |
| Undiscoverability test | Only document what agents can't find by exploring | Agents that build own context outperform pre-loaded context; docs should contain decisions, conventions, failure modes |
| Agent readiness assessment | Evaluate feedback loops, module structure, and risks during setup | Architecture and feedback loops affect agent output more than context files — surface gaps early |