Atlas

Atlas gives AI coding agents enough local project context to work inside a GoForj App without guessing at framework conventions.

It is optional, but first-class. During forj new, the Atlas - Agent Support step can install agent guidance for the tools you use. Atlas can also be added later from an existing project.

Install and Verify

During project creation, run the wizard:

forj new

At Atlas - Agent Support, choose Recommended to install guidance for one preferred locally installed agent and enable local docs context. Choose Custom when the Project deliberately supports more than one agent.

For an existing GoForj Project, install Atlas and verify the result:

forj atlas:install
forj atlas:doctor

Expected result: Doctor reports Atlas installed: true, shows which agents are configured, and lists the installed guidance, skills, and MCP surfaces. Once installed, agents can read the local project guidance without another daily setup command.

Preview an install or update without changing the Project:

forj atlas:install --dry-run
forj atlas:update --dry-run

What Atlas adds

Atlas installs lightweight project files that teach agents the GoForj way to build:

• prefer forj make:* commands over hand-created framework files
• keep business code package-scoped under internal/
• register routes, commands, jobs, schedules, subscribers, and providers through the App composition points GoForj creates
• use the selected app in a multi-app Project
• read local docs and project metadata before changing code

The goal is not to make agents louder. The goal is to make them less surprising.

Native files and project state

Atlas records the selected agents, enabled features, and generated-file ownership in .goforj/atlas.json. Commit that file with the Project. Agent files remain in their native discovery locations—such as AGENTS.md, .agents/skills, and .codex/config.toml for Codex—but Atlas writes them only for selected agents.

A normal update follows the committed selection. It does not add every agent installed on the machine or infer new agents from directories Atlas generated previously:

forj atlas:update

Re-run local agent discovery only when you intend to change the selection:

forj atlas:update --discover

Explicit --agent selections replace the committed agent set. --all-agents remains available for teams that intentionally commit every supported projection. When an agent or installation feature is deselected, Atlas removes its own guideline block, MCP entry, and recorded generated skills while preserving unrelated configuration and user-authored content.

Project-owned skills

Atlas ships with built-in GoForj skills, but your project can add its own.

Put repo-owned skills under .ai/skills:

.ai/
  skills/
    checkout-rules/
      SKILL.md
    support-runbook.md

You can scaffold the directory and starter file:

forj atlas:make-skill checkout-rules

Then sync Atlas skills:

forj atlas:update --skills

Atlas copies those skills into each selected agent's native location:

.agents/skills/checkout-rules/SKILL.md             # Codex
.claude/skills/checkout-rules/SKILL.md             # Claude Code
.github/instructions/checkout-rules.instructions.md # GitHub Copilot
.gemini/skills/checkout-rules/SKILL.md             # Gemini CLI

Use project-owned skills for conventions that only exist in your repo: package boundaries, domain naming, deployment rules, generated file ownership, review expectations, or local testing habits.

Keep them short and specific. A good project skill tells the agent what to do differently in this codebase.

Example:

# Refund Review Rules

Use this skill when changing staff refund review, payment adjustment, or order-dispute workflows.

Rules:

- Keep payment provider calls behind `internal/refunds.PaymentGateway`.
- Use `forj admin make:*` for generated staff operations entry points.
- Run `forj admin test:refund-review` before marking refund-review work done.
- Do not add direct provider SDK calls inside HTTP controllers.

Atlas guidance also tells agents to notice durable repo knowledge. When you teach an agent a convention, workflow, command, or review expectation that is likely to matter again, the agent should briefly ask whether it belongs in .ai/skills/<name>/SKILL.md.

That suggestion should be rare and practical. It is for repeated project knowledge, not one-off preferences or temporary debugging steps.

Customize the Installation

Choose individual agents and surfaces when you want a smaller or more explicit install:

forj atlas:install --agent codex --agent copilot --agent gemini --guidelines --skills --mcp

Supported agents

Atlas is designed around local project files and editor-readable instructions, so the same project can support multiple agents:

• Codex
• Claude Code
• GitHub Copilot
• Gemini CLI

If an agent is not detected, you can still choose it during custom installation.

Atlas writes each agent's native project files:

Agent	Guidance	Skills	MCP config
Codex	AGENTS.md	.agents/skills/*/SKILL.md	.codex/config.toml
Claude Code	CLAUDE.md	.claude/skills/*/SKILL.md	.mcp.json
GitHub Copilot	.github/copilot-instructions.md	.github/instructions/*.instructions.md	.vscode/mcp.json
Gemini CLI	GEMINI.md	.gemini/skills/*/GEMINI.md	.gemini/settings.json

MCP context

Atlas can expose GoForj context through an MCP server. The MCP server loads docs and project metadata locally, then serves focused slices of context to the agent.

The server is run by the GoForj CLI:

forj atlas:mcp

Atlas keeps the docs in a local cache and updates them from the GoForj docs repository. If you are working from a local docs checkout, point Atlas at it:

GOFORJ_DOCS_PATH=/path/to/goforj-docs/docs forj atlas:mcp

To use cached hosted docs from a branch, tag, or commit, select the repository and ref before starting MCP:

GOFORJ_ATLAS_DOCS_REPO=https://github.com/goforj/docs.git \
GOFORJ_ATLAS_DOCS_REF=main \
forj atlas:mcp

Use a tag or commit only when that ref exists in the docs repository. Framework release tags and docs repository refs are separate namespaces.

Atlas reports the active docs version and revision through application-info and docs-section-pack, so an agent can tell which docs bundle it used.

Use version-alignment when an agent needs to compare the project GoForj version, Atlas version, and active docs bundle before following docs from a branch or release.

Workflow skills

Atlas installs workflow skills for high-leverage GoForj changes. They are short, task-focused guides that tell an agent which app owns the change, which forj make:* command to prefer, which generated files not to edit by hand, which docs sections to read, and which validation commands prove the work.

Built-in workflow skills cover:

• HTTP routes, controllers, and services
• app-owned CLI commands
• queued jobs and worker behavior
• scheduler registrations
• events and subscribers
• repositories, migrations, caches, storage, and named data resources
• Wire repair
• runtime debugging with logs, routes, URLs, browser logs, metrics, and Lighthouse context
• multi-app changes
• validation planning

Atlas also includes starter-kit overlays for Vue, React, and templ/htmx projects. When a frontend task touches pages, screens, dashboards, login, auth, or UI behavior, the workflow plan can point the agent at the matching starter-kit skill so edits stay in the owning app's frontend tree.

Agent workflow examples

Agents should use Atlas tools together instead of reading the whole docs site or guessing from filenames.

For a route change:

workflow-plan task="add users route"
docs-section-pack workflow_id="goforj-add-http-route"
generated-file-policy path="app/routes.go"
command-advice task="add users route" resource="users"
validation-plan task="add users route"

That sequence gives the agent the preferred command, app registration points, focused route/controller/Wire docs, file ownership guidance, and the checks that prove the route is registered.

For an operations job owned by the additional admin app:

workflow-plan app="admin" task="add reconcile refunds job"
docs-section-pack workflow_id="goforj-add-job"
resource-inventory
command-advice app="admin" task="add reconcile refunds job" resource="reconcile-refunds"
validation-plan app="admin" task="add reconcile refunds job"

That should lead to forj admin make:job reconcile-refunds, app-scoped Wire registration, small typed queue payloads, and worker validation rather than an untracked goroutine or anonymous queue callback.

For a Wire failure:

wire-diagnostics output="<forj build output>"
registration-points
docs-section-pack workflow_id="goforj-wire-repair"
generated-file-policy path="app/wire/wire_gen.go"
validation-plan task="fix wire missing provider"

That keeps the fix in the provider set that owns the dependency and reminds the agent not to edit wire_gen.go or hide required constructor dependencies behind nil guards.

For runtime debugging:

workflow-plan task="debug dashboard 500"
resource-inventory
runtime-snapshot app="app" runtime="http" path="/dashboard"
debug-plan app="app" runtime="http" path="/dashboard"
get-absolute-url app="app" path="/dashboard"
read-log-entries app="app" limit=50
last-error
metrics-metadata app="app" runtime="http"
browser-logs app="app" limit=50

That gives the agent app/runtime identity, local URLs, recent logs, metrics labels, browser errors, and known operator resources before code changes begin.

For human-readable versions of common evidence loops, see Atlas Debug Recipes.

runtime-snapshot and debug-plan are evidence tools. They report missing logs, URLs, routes, browser entries, metrics targets, or resource links instead of inventing values.

generated-file-policy reports classification, preferred action, and ownership for generated files, app-owned files, app-specific files, migrations, frontend files, config, docs, and unknown paths. Projects can override ownership rules in .goforj/atlas.json.

Daily use

Most users do not need to run Atlas commands every day. Once installed, your agent reads the local guidance files and, when configured, asks the MCP server for focused docs context.

Reach for Atlas commands when:

• you add or remove an agent
• you want to refresh installed skills or instructions
• you want to point MCP at a local docs checkout
• you want agents to understand a newly rendered GoForj project
• you deliberately want to re-detect the preferred local agent

Useful commands:

forj atlas:install
forj atlas:update
forj atlas:doctor
forj atlas:list-skills
forj atlas:make-skill checkout-rules
forj atlas:mcp

forj atlas:doctor reports whether Atlas is installed, which agents are configured, whether generated skills look stale, and which MCP/guidance files are present.

Related

• Quickstart
• Make Command Reference
• Apps
• Organizing Generated Code