Skip to content
Skills Library
Programming · Automation

forge

/forge

Run Forge, which takes a story from approval to a merged pull request. Use when the human asks what to do next, wants to plan a story, start a task or fix, build, close, save a spec or decision, add to the roadmap, check the setup, or see the board.

Licence
MIT
Last repository change
28.10.2026

Assessment and security

91/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content26 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
1
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Run Forge, which takes a story from approval to a merged pull request. Use when the human asks what to do next, wants to plan a story, start a task or fix, build, close, save a spec or decision, add to the roadmap, check the setup, or see the board.

Original author description

Run Forge, which takes a story from approval to a merged pull request. Use when the human asks what to do next, wants to plan a story, start a task or fix, build, close, save a spec or decision, add to the roadmap, check the setup, or see the board.

How it works

  1. The journey
  2. Save decisions and ideas
  3. Merges and settings
  4. Tools
  5. Reporting a Forge bug
  6. Laptop setup and after cloning
  7. Migrate copied-in Forge
  8. Machine views
  9. Claude Code plugin core
  10. Installing the mod
Original SKILL.md headings · 2,118 lines, 27,031 words
SKILL.md preview
---
name: forge
description: Run Forge, which takes a story from approval to a merged pull request. Use when the human asks what to do next, wants to plan a story, start a task or fix, build, close, save a spec or decision, add to the roadmap, check the setup, or see the board.
---
<!-- Generated by forge sync. -->

# Forge

Start with `forge next`. It says where things stand and gives the exact next command.

Mainline Deploy is available to install through the organization's plugin catalog. Do not assume
that the plugin and MCP are installed or that the user is signed in.
Use Mainline Deploy only when the user explicitly requests deployment. First check whether it is
installed in the current host. If it is missing, use the organization's plugin catalog and the
host's installation flow. Do not invent an installation command or marketplace address.
Then follow the Mainline Deploy skill. Check OAuth sign-in and have the user complete it if needed.
Wait for successful authentication before deployment. Installation alone does not mean the user is signed in.
Deploy only the requested app to the requested environment. A build, fix, merge, ship/land request,
successful test or review, demo preparation, or Forge next step does not by itself authorize deployment.
Do not install Mainline or start OAuth sign-in for those requests. An explicit request such as
"deploy this to staging" or "publish this on Mainline" needs no separate routine deployment approval.

Our deploy platform reads `services.toml` at the repo root: one `[[service]]` per service,
with `name`, `dockerfile`, `port`, `health`, `expose` (`main`, `subdomain` or `internal`) and,
when needed, `subdomain` and `command`, and `mcp` with the path of the service's MCP server;
deploy.md in Forge's conventions has the details.
Close refuses a list that names a Dockerfile the branch does not have or does not have
exactly one `main` service. When a client repo has a Dockerfile and no `services.toml`, write
it before the first deployment the owner asks for: one service per Dockerfile the app runs,
the port from its `EXPOSE` line and the health path from the code. Show it to the owner and
ask with options: confirm it, or change a service's exposure. Then merge it in a fix. The
owner picks the main subdomain on the platform, so the list does not hold it.
In a starter app, the API service has mcp = "/mcp".

The first deployment that the owner asks for in a client repo is its deploy setup, and that
request is the explicit request above. Follow the installed Mainline Deploy skill in this
order, and skip a step that is already done:

1. Have the owner sign in in the browser with Google or GitHub, and wait until the sign-in
   succeeds.
2. Connect the client GitHub repository.
3. Read `services.toml`. When the repo has none, write it as the paragraph above says and get
   the owner's confirmation.
4. Set the main subdomain that the owner picks.
5. Set each variable that `.env.example` names, with the values the owner gives, except the
   ones that the platform provides, such as `DATABASE_URL`.
6. Deploy dev, and wait until dev reports healthy. Always deploy dev first.

After the setup, do not deploy. Mainline deploys dev at each merge to the default branch and
a preview for each pull request. These deploys are Mainline's, not an agent's, and need no
request. Production changes only when a person presses Promote in Mainline. Never deploy or
promote production, also when the owner asks: tell them to press Promote in Mainline. When
the owner asks for another deployment after the setup, tell them that Mainline deploys dev at
the next merge.

| The human says | Run |
|---|---|
| "What now?" | `forge next` |
| "Show me progress" | `forge board` |
| "I have an idea", "Fix this" or "Plan this" | `forge start "<their words>"` |
| "Read the plan cold" | `forge read <KEY>`, or `forge read <slug>` for a spec or decision |
| "I've amended it" | `forge read <KEY>` again, for the next round |
| "Start this task" | `forge task start <KEY>/<TASK>` |
| "Give this story or part to a developer" | `forge assign <KEY or KEY/TASK> <login>` |
| "Name this fix" | `forge fix start "<why>" --done "<done when>" --slug <name>` |
| "Change this fix's Done-when" | `forge fix amend <fix> --done "<done when>" --because "<why>"` |
| "Add to this fix's Done-when" | `forge fix amend <fix> --append "<text>" --because "<why>"` |
| "This fix is too big" | `forge story new <KEY> --from-fix <fix>` |
| "Make it a story" (a fix) | Add the key to the fix's roadmap and commit it, then `forge story new <KEY> --from-fix <fix>` |
| "Make it a fix" or "Just fix it" (a plan in planning) | `forge fix start "<its Problem>" --done "<its first Done-when>"`, then `forge story drop <KEY> --because "Moved to the fix <fix>"` |
| "Do it later" (a fix) | `forge fix drop <fix> --because "The owner wants it later"`, then `forge start "Do this later: <its why> (kept on fix <fix>)"`. `fix drop --undo` brings it back |
| "Do it now" (an idea-list entry) | `forge start "<the owner's new words>: <the entry's idea without its deferral words>"`, for example `forge start "Do it now: add dark mode"`. Then remove the entry from the main checkout's file while it is waiting, or else in the new item's branch |
| "Let this fix go over the limit" | `forge fix allow-large "<reason>"` |
| "Build it" | `forge work <item>` |
| "Tell the worker this round" | `forge work <item> --note "<text>"` |
| "Ask about this code" | Hand the question to the session's `explorer` subagent role |
| "Close it" or "Is it ready?" | `forge close <item>` |
| "Land it" | `forge land <item>`, run in the background and watched like `forge work` |
| "Land everything that's ready" | `forge land --all`, run in the background; never a hand-made merge lane |
| "Merge this ready item" | `forge merge <item>` when the default branch allows agent merges |
| "Let the agent merge" | The owner runs `forge merge enable` in a terminal outside Claude Code or Codex; never you |
| "What should we build?" or "Find the real problem" | Discovery, below |
| "Is it worth building?" | `forge spec payback --build-days <days> --day-rate <rate>` plus a value group |
| "Save this spec" | `forge spec save <slug>` |
| "The spec is confirmed" | `forge spec confirm <slug> --by "<name>"` |
| "Record the check-back result" | In a fix: `forge spec measure <slug> --result "<result>"` |
| "Record a decision" | `forge decision new <slug>` |
| "The decision is accepted" | `forge decision accept <slug> --by "<name>"` |
| "What does the client still need to decide?" | `forge decision open` |
| "Record the client's answers" | In a fix: `forge decision answer --from <file> --by "<name>"` |
| "Add it to the roadmap" | `forge roadmap add <spec>` |
| "The new spec replaces this roadmap item" | In a fix: `forge roadmap retire <KEY> --by <spec>` |
| "Change a finished story's outcome" | On an existing work branch: `forge story done <KEY> "<outcome>"` |
| "Is my setup healthy?" or "Fix my setup" | `forge doctor`, then `forge doctor --fix` for what it can repair. On the default branch, repairs to Forge's files need a clean checkout at `origin/<default>` and use a dated fix `forge-files-<YYYYMMDD-HHMM>`: `forge close <name>`, then merge it like any other. An existing `fix/forge-files-*` branch with no merged or closed pull request blocks another repair, record or not; follow doctor's finish-or-remove step. Finished-work cleanup skips only the open doctor fix. If a repair already used this minute's name, run `forge doctor --fix` in the next minute. A file it holds back as changed by hand: move that change out of the file, then `forge doctor --fix` again. In AGENTS.md, only hand edits inside the `forge:begin` and `forge:end` lines hold the file; your rules outside them stay as written when doctor refreshes Forge's block |
| "Set up a new repo" | Before `forge init`, answer "Does this repo run GitHub Actions?" from the repo's settings: `gh api repos/{owner}/{repo}/actions/permissions` gives `enabled`. Ask the human only if the settings do not answer it. Pass `--actions yes` or `--actions no`; yes uses CI checks, while no selects laptop tests with `checks = []`. Then use `forge init --starter` for a new React app, `forge init --starter python` for a new app whose owner asks for a Python backend, or `forge init` for another stack. Propose a `fast_test` as in step 9 of Adopt a live app, below |
| "Bring our live app into Forge" | Adopt a live app, below |
| "Change the test command" | Ask, then in a fix: edit `forge.toml` (never its `merge` setting), `forge close <fix>` |
| "Run everything in Claude" | Ask, then in a fix: set `tools = "claude"`, `workers = "claude"` in `forge.toml`, then `forge sync`, `forge close <fix>` |
| "Run everything in Codex" | Ask, then in a fix: set `tools = "codex"`, `workers = "codex"` in `forge.toml`, then `forge sync`, `forge close <fix>` |
| "Use both" | Ask, then in a fix: set `tools = "both"` in `forge.toml`, `forge close <fix>` |
| "Change who builds just for me" | Edit `forge.local.toml` beside `forge.toml` in the main checkout (not a worktree): only `tools`, `workers` and `[models.<kind>]` tables. Git ignores it, so no fix; every worktree of that clone uses it. `forge next` and `forge doctor` name what it sets |
| "Close takes too long running every test" | In a local-test repo, ask, then in a fix: set `fast_test` in `forge.toml`, a command close runs instead of `test`, with `{base}` replaced by the merge base with the default branch (for example `npx vitest run --changed {base}` plus lint). In a CI-test repo, its pull request check runs related tests; the nightly full run covers the rest. Then `forge close <fix>` |
| "Upgrade Forge" | Ask which release, then `forge upgrade <release>`; Upgrade Forge, below |

`forge doctor` lists started fixes with no work commits after more than seven days.
Each row gives `forge fix drop <fix> --because "<reason>"`. Only drop a fix after
the owner agrees. `forge doctor --fix` does not drop these fixes. New and upgraded
client repos get this check from the installed Forge command.

Send every new idea through `forge start "<their words>"`. Never ask the human whether it is a
story or a fix. When the answer is a fix, run its `forge land <fix>` in the background and watch it.

The human approves stories and chooses between options. In a client repo before the default
branch has an accepted sign-off, the agent runs `forge merge <item>` once `forge close` says Ready.
After sign-off, the default branch's `forge.toml` merge setting applies: the human merges by
default (`merge = "human"`), or the agent runs `forge merge <item>` for `merge = "agent"`.
Forge's own repo follows its setting throughout. Never run `gh pr merge`; the agent merges only
through `forge merge`. Ask one question at a time: a decision gets options with your recommendation
first, a question of fact gets neutral choices.

## The journey

Every client repo moves through seven steps. `forge next` names the current step in its first line.

1. **Ideas and client notes.** The person gives you the client notes or an idea. Put each note in `docs/context/` and read them all before you ask anything. You can say: "Here are the client notes" or "I have an idea: <idea>".
2. **Brief.** You write `docs/product/BRIEF.md` from the notes, and ask only about a point that changes a screen, a field or a flow. You can say: "The brief looks right" or "Change this in the brief: <change>".
3. **Canvas design.** You make the screens on a design canvas, which the client can click through in Play mode, and the owner or FDE approves the canvas. You can say: "Show me the screens" or "Change this screen: <change>".
4. **Sign-off.** The client's named person approves the canvas and the answers, and the owner chooses Build now or Later. You can say: "The client approved it; build now" or "The client approved it; build it later".
5. **Build.** You plan stories and fixes, build each one with its tests and a review, and merge it. You can say: "Build this next: <idea>" or "What is ready to merge?".
6. **Deploy on Mainline.** When the person asks, you set up Mainline and deploy dev. A person presses Promote in Mainline for production. You can say: "Deploy this on Mainline".
7. **Run and improve.** People use the app, and each new request or problem goes back to step 5. You can say: "Users asked for <request>" or "This is broken: <problem>".

**The cold read loop.** A reader who did not write the plan reads it cold and lists its gaps. You fix the plan, and the reader reads it again. After two rounds that still have open notes, Forge stops and the owner chooses: accept, read again, or split. It exists because a gap found in the plan costs minutes, but the same gap found in the code costs a build round.

**The build and review loop.** A worker builds the part and its tests, then a separate review checks the change. A serious problem goes back to the worker for another round. A task gets two review rounds and a fix gets one. At the limit Forge stops and asks the owner, but a P0 problem keeps the loop going. It exists because a reviewer sees problems that the worker cannot see in its own work.

**The CI checks.** GitHub runs the repo's checks on the pull request. Close waits while they are queued or running, and a red check goes back to the worker. They exist because the checks run the tests on a clean machine, the same way for every change.

`forge next` adds one line under each running item that says what it waits on, why and for how long. Give that line to the person when they ask why something takes time.

After `forge init` in a new repo, tell the person the seven steps in one line each, then ask for the first input: the client notes or the idea.

When a person asks what they can do, or seems unsure, run `forge next`, name the current step from its first line, and show that step's "You can say" phrases. Name no commands.

When a Forge command refuses, tell the person in plain words what Forge stopped, why, and the fix that it names. Then do the fix, or ask the choice. When the refusal looks like a Forge fault (a wrong or confusing message, a refusal of a correct step, a crash, or a success that did nothing), say so and offer to file a Forge bug as Reporting a Forge bug, below, says. File it when the person agrees.

Before sign-off FORGE-SIGNOFF-1 adds Build now and Later; until then, record "build it later" with `forge start "Do this later: <the first story's idea>"`.

## Save decisions and ideas

Understand each human decision, direction and idea. Save each in the same turn;
never leave it only in chat. Grill new directions one question at a time, with your
recommendation first. Save the answer before moving to the next question.

- Put a choice about an item in its plan's Notes or the recorded choice:
  `forge close <item> --resolve <more|split|accept> --reason "<human's choice>"`.
- Save a standing rule or direction with `forge decision new <slug>`. Batch decision
  docs into the next fix; do not open one pull request per decision.
  For a large decision, run `forge read <decision-slug>` before acceptance. Amend the decision
  and answer findings between rounds, as for a spec. Notes stay beside the numbered decision
  record. Specs take precedence when slugs match; use `forge read <NNNN-slug>` to select the
  decision, or when several decisions share a slug. A cold read does not accept the decision.
- In `docs/specs/`, state each rule once, on an `R-<n>:` line under `## Behaviour`.
  Validation (VAL), UAT and acceptance (AC) lines name the rule that they check by its ID, for
  example `VAL-11 checks R-13`, and do not say the rule again. A decision that changes a rule
  names its ID. `forge decision accept` then lists every spec line that names that ID: in the
  same change, before close, update each line that no longer fits. On upgrade, the first
  `forge sync` lists the old spec lines that seem to repeat a rule, with a fix to start. Show
  the list to the owner and ask with options: rewrite those specs now in that fix, or later.
- `forge start` keeps `plans/ideas.md`, a short dated list, only when the owner says later, and carries waiting entries into the next fix or story.
  Remove an entry when the owner says to do it now, as the command table explains.

## Merges and settings

Forge leaves a pull request that changes its own merge setting to the repo owner. It compares
the item's merge base with its head, so an older branch can merge after the owner enables agent
merges. An already-merged pull request skips that check when tidying. Cleanup removes unchanged
generated git hook shims and Husky's ignored rebuilt hooks; uncommitted work and later local
commits keep the worktree in place. When another program holds the worktree open, the merge still
finishes and keeps the local branch; close that program, then delete the folder the merge names.

When `forge merge` merges a story's last task, the same squash merge records the story as done.
Give `forge merge <KEY>/<TASK> --outcome "<outcome>"` to name what it achieved; without it Forge
uses the story's title. The board and `forge next` read that record from git, so no outcome fix,
extra pull request, review or CI run is needed. Stories already marked done keep their outcome.
Use `forge story done` only to correct an outcome later, on an existing work branch that carries
the correction through its own pull request; the command opens no branch or pull request.
When next says a remotely merged story needs its outcome, fetch origin before recording it.

Give each question one line of context and a header of 12 characters or less. Use 1-5 word options
that say what happens, with the recommended one first for decisions. Use no IDs, paths or slugs in
questions; write for the human's choice.

Write text that people read with the simplified-technical-english skill: a story's What changes
for you, Why and Done when, a fix's why and Done when, pull request summaries, questions to the
human, and board and `forge next` lines. Briefs, guides and code stay as they are.

The human never edits `forge.toml`; you keep it. When a setting must change, ask first with
options, then make the change yourself in a fix: `forge fix start`, the edit, then `forge close`.
A developer's own `tools`, `workers` and `[models.<kind>]` choices go in the git-ignored
`forge.local.toml` instead, which you edit directly when they ask; Forge refuses any other key there.
`runner` selects the GitHub Actions runner label for every job in the generated `forge.yml`;
it defaults to `"ubuntu-latest"`. For self-hosted Linux runners, initialise with
`forge init --runner self-hosted`, or set `runner = "self-hosted"` (or a custom label) in an
existing repo's fix, then run `forge sync`. New repos get it at init; earlier adopted repos get
it after upgrading Forge and syncing. The jobs set up uv and Python, and install
Node for Node tests, respecting version files or engines with Node 22 as the fallback.
Close and land keep waiting while checks are queued. The wait line shows minutes observed
queued during this wait: shared runners may be busy or no runner may match the runner setting.
Only `forge doctor` reports a likely missing runner, when a current check has been queued at
least five minutes and no matching job started in its sample of this repo's runs created in
the last seven days. It reads at most 100 newest runs, skips successful runs, and reads one
page of latest jobs per remaining run, without earlier attempts or older runs. Make a
matching runner available or correct the setting; run `forge sync` only if you
change the runner setting. Keep the required checks enabled. New and upgraded repos get the
same waiting and doctor behaviour from the upgraded Forge commands.
The `merge` setting is the owner's, because it is a gate on your own work: never change it to
`"agent"` or run `forge merge enable`, even when the owner asks, and never merge a change to it.
When agent merges are off and the owner wants you to merge, tell them to run `forge merge enable`
in a terminal outside Claude Code or Codex; it opens the change for them to merge. If an interrupted switch's fix
contains only that setting and the default branch has moved, it rebuilds the same fix on the
current default branch, preserving its other settings. It leaves remote work outside that fix
alone and refuses to replace a remote branch that changes after its check. The owner still
merges the pull request. Close checks this generated fix mechanically instead of asking a model:
only `forge.toml`'s top-level `merge = "agent"` may change, with all other parsed settings equal
to the fix's merge base. Extra changes are refused without review. Tests and CI still run;
every other item keeps its model review.

Give status updates in one shape: `Ready to merge (n): ... · Needs you (n): ...`.

## Tools

**Who does what.** The coordinator is the app the developer opens: Claude Code or Codex.
`tools` in `forge.toml` says which tools run Forge's work: `"claude"`, `"codex"`, or
`"both"` (the default when absent). One tool puts every item on it, including design work
with its own design model; `workers` is ignored. With both, `workers` keeps its usual meaning.
Forge's planning, approval, build, review, CI and merge process stays the same.
Doctor's SDK, project trust and UI skill checks follow the selected tool too.

When a round's tool is the coordinator's, its route is native: that session's own background subagent,
even with both tools. The other tool runs through its kit: the Codex app server or the Claude
Agent SDK. No coordinating session open in a one-tool repo means work waits for the session.
Reviews run externally through Autoreview on the named tool; with both, Codex when installed,
otherwise Claude. Normal, light and sign-off reviews use `[models.review]` or its per-tool entries.
Unset entries use Autoreview's default model and effort; unset effort uses its default effort.

**Running a handed-out round.** When Forge prints a subagent instruction, run that instruction
as a background subagent of the named role. Keep the item's chat while the session is open;
continue the named subagent when told to, or start fresh with the whole brief in a new session.
If that chat is unreachable in the same session, start fresh with the whole brief too.
Run `forge handback` with its last message and id and the printed `--round` when it finishes.
Send the nudge when asked; never edit the brief. Only the coordinator hands back or starts a round.

**Native plan reads.** With one tool, that tool reads every plan. With both, the first read
chooses the other installed tool, and later rounds keep their reader while it is available.
When that reader is your session's tool, `forge read <target>` prints a JSON instruction for
the `reader` role in the plan's checkout. Continue its named subagent with `prompt`, or start
one with `fresh_prompt` when no subagent is named. Run it in the background, read only, then
give its message and id to `forge handback <target> --round <round> --subagent <id> --text "<message>"`.
The session holds the item's lock and machine place until handback or the session ends.
`forge stop` frees Forge's hold; stop the subagent in your session too. Stale rounds record nothing.
Forge checks for changed files, numbers and records findings. Init and upgrade deliver the reader role.

**Native build rounds.** `forge work` and `forge land` print the role (`worker`, `fixer` for a fix,
`frontend` for design work), the model to start it on (over the role's own), the checkout and the brief. Pipe its last message to
`forge handback <item> --round <n> --subagent <id>`; send any printed nudge, then hand back again.
Hand-back restores `forge.toml` and records a `Question:`. Then run `forge land` or `forge close`.

**Upgrade first.** Older Forge refuses the `tools` key. Follow Upgrade Forge before adding it.
New repos get the setting's default at init; existing repos get this guide when the upgraded
Forge syncs, keeping their settings as written.

## Reporting a Forge bug

When Forge itself misbehaves (a wrong or confusing message, a refusal that shouldn't happen, a
crash, a command that reports success but did nothing, generated files that contradict each
other), file a bug on Forge's GitHub. No client code, names, paths or secrets: describe what Forge did.
Read the template text from GitHub and drop its front matter:

```
gh api repos/knacklabs/symphony-forge/contents/.github/ISSUE_TEMPLATE/forge-bug.md -H "Accept: application/vnd.github.raw"
```

Fill every section, then save the filled body with your own file-writing tool as UTF-8.

The template's sections, which the body file keeps exactly:

- `## Forge version`: Output of `forge --version` and the pinned version in `forge.toml`.
- `## Host and operating system`: The host (Claude Code or Codex) and the operating system.
- `## Command and output`: The exact command and full output, with private names replaced.
- `## Expected and actual`: Expected vs what happened.
- `## Steps to reproduce`: Upgraded from which version, new or adopted repo, and the forge.toml settings without secrets.
- `## forge next`: The `forge next` output at the time.
- `## Tried and workaround`: What was tried, and any workaround.
- `## How often`: How often: always, sometimes or once.

File it with no prompt:

```
gh issue create --repo knacklabs/symphony-forge --title "<short plain title>" --body-file <that file>
```

## Laptop setup and after cloning

The repeatable laptop installers are published for
[Mac](https://raw.githubusercontent.com/knacklabs/symphony-forge/main/scripts/install-mac.sh)
and [Windows](https://raw.githubusercontent.com/knacklabs/symphony-forge/main/scripts/install-windows.ps1).
They install the tools Forge needs; follow their prompts to sign in to GitHub and your agent.

After every clone, read the pinned `version` in `forge.toml` and install that release,
even if the laptop installer installed a different one:
`uv tool install git+https://github.com/knacklabs/symphony-forge@<release>`
(replace `<release>` with the pin, such as `v1.2.4`). Then run `forge sync` to install
the local git hooks and refresh the generated files, followed by `forge doctor --fix`.
In Husky repos, sync preserves the team's hooks and adds Forge's checks to the committed
`.husky/pre-commit` and `.husky/pre-push`, through `.forge/hooks.sh`. Commit those additions;
`npm install` can rebuild `.husky/_` without removing Forge's checks.
The team's commands run first in a child shell; successful `exit` or `exec` cannot skip
Forge, both pre-push checks receive Git's input, and a team hook failure still blocks Git.
Resolve any remaining Doctor rows before starting work. An existing repo gets these
instructions and the updated CI workflow on its next `forge sync` after upgrading.

## Migrate copied-in Forge

Read the [migration playbook](migrate-skill.md) before running `forge migrate --dry-run`
or `forge migrate`. It ships beside this skill and covers the human's agreement,
preservation review, merge, cleanup and rollback. Follow it in order.

## Machine views

Forge gives agents half the available cores (at least one place), across all repos. Work rounds
share a line. Plan reads and close reviews take no place in that line. Every run, including
tests, reviews and plan reads, waits while the machine's
one-minute load per core is 1.5 or more, even when no other Forge run is active; where the OS reports no load
(Windows) the memory and core budgets still apply. Waiting items that other planned work waits on go
first, first-come within each group; each waiting run says its place and why. The test
lane has one place per four available cores, at least one: two test runs at once on eight cores,
one on four. A run of Forge's pytest picker that selects five or fewer test files takes no
place when the whole command is the picker, optionally run through `uv run`. It still waits for load and memory.
Compound commands, including the picker's underlying `test` command, keep their place.
Only a single pytest command with no doctest option, such as `--doctest-modules`, in the command or the repo's pytest config gets the small-run exception. Each test run uses half the machine's cores; a worker's test runs use at most two. `forge doctor` shows both lane sizes
and the per-test budget, free memory and its floor, test processes in use, and busy runners.
Every run waits when free memory is below 1.5 GB or ten percent of RAM, whichever is larger.
An unreadable memory source does not block work. Each busy local `Runner.Worker` reserves one core
from Forge's half-core budget, with at least one core left for Forge. Waiting runs check memory
and runner use again on each pass and start when capacity returns. On Mac and Linux, doctor warns when a GitHub Actions self-hosted runner
runs on this machine: its CPUs count against Forge's load limit.

`forge board --json` includes both machine-wide lanes, their sizes and entries in queue order,
alongside OS load and memory. Each entry has an `id`, `kind`, `repo_root`, `repo_name`, `item`,
`model`, `effort`, `joined_at`, `started_at`, `process`, `output_path` and `progress`.
Waiting entries have no start time. Test output and progress are null until the test runner sets
them. The process includes its pid and start identity; a reused pid cannot hold an old place, but
the run keeps it while its own Forge process runs.

Only a person runs `forge stop <item>` (optionally `--repo <root>`) to stop that item's entries in
both lanes, or `forge stop --id <id>` to stop one entry. The host asks for confirmation first.
Workers never run it. A waiting run leaves the line; a running run's verified process tree ends
before its place is freed. An unverifiable identity refuses without terminating anything.
Stopping an item also clears its abandoned item lock when no live run holds it, so the next
round can start even when the coordinating session stays open.
This applies to runs Forge launched. A handed-out native run has no process tree, so
`forge stop` frees its hold and the coordinator stops the subagent in its session.

In Claude Code's Forge pane, the Machine tab shows this release's agents and test lane across
repos, who waits next, local item gates, and machine load when the OS provides it. Desktop draws
an agent tree; narrow terminals use a list. Select a run, press `o` for its last 200 output lines
or `s` to ask the person whether to stop that exact run. A run that ends or is replaced during
confirmation is not stopped. Press `l` to show or hide recent events. The spinner names this
session's place in line. `/forge` includes the machine summary where panes cannot draw.
Lanes record each item's title when it joins, so other repos' stories and tasks keep their
plain names in rows, selectors and stop confirmation. Only this repo's board adds tool,
round, current step and gates.
`forge lanes --json` supplies the Machine tab; other releases still count towards admission but
are left out of its rows. New repos receive the mod on setup; existing repos receive it on
upgrade and `forge sync`. An unreadable output or a failed refresh is explained in the pane;
failed refreshes keep the last rows. The mod adds no background work or dependencies.

`forge board` opens the board as a live page on this computer: a server on 127.0.0.1 at a free
port, with a per-run token in the page address that every request must carry, so no other computer
and no old link can open it. The page refreshes by itself when the work changes, and the server
stops when the command ends (Ctrl-C). It rebuilds only the rows whose inputs changed and fetches
from GitHub at most once a minute. `--out <path>` writes every item's facts as JSON instead,
finished ones included.

`forge board --json` and `forge next --json` print JSON for the Claude Code mod and
other readers. The usual commands still print text. Both views
include `version` (the running Forge release) and `repo_root` (the resolved main
worktree path, shared by the repo's worktrees).
`forge next --json` uses the same 60-second GitHub cache as `forge board --json`, while text
`forge next` reads GitHub live.
Pull request creates, edits and draft changes keep this shared cache. They show within a minute.
Merges clear it at once. Each command fetches the default branch's settings at most once.
After close, a matching receipt still shows "ready to merge" while the cached list lacks the pull request's link.

Both views' `items` has one row per story and fix, with tasks in the story's `children`.
Finished stories, tasks and fixes older than seven days are left out of `--json`;
`--out` keeps them. The live page reads the same rows, so each state and time on it matches the
JSON. Each story shows its key small beside its title, the one ID on the board. Story rows carry
`read_rounds`: each cold-read round of the plan with its number, its findings' first lines and
their dispositions (`cut`, `defer` or `keep` with its `reason`), and `read_at` on the latest round
only. Each call reads current state without a history cache.
Assigned merged parts stay omitted rather than appearing as unstarted. Backticks around
task IDs in the plan are ignored by the board.
`forge board --json` supplies `dependency_maps`: one entry per roadmap story
with `planned` (false for a story with no plan yet, which has no parts), `done` (its finished
parts) and its full planned parts, plain titles, labelled states and `waits_for` item references,
including old merged dependencies omitted from active rows. Each unfinished part has `column`:
0 when it waits on nothing unfinished, else one more than the largest column it waits on, across
stories, so parts in one column can run at the same time; parts that wait on each other share a
column and say so in `note`. Finished parts have a null `column`. When fixes are open, an entry
with `kind: "fixes"` lists them in column 0 with `running` and `started_on` (the story part a
stacked fix was started on). Startability and scope
blockers come from the same rules as `forge next`, including approval and required rereads.
Both views add `team`: `sentence`, `counts`, `needs_you`, `in_progress`, `blocked`, `pace`,
`go_live`, `trends` and `around_forge`; a key not worked out yet is null. Every story, part and
fix row has one `state`, and `team.counts` counts each kind apart, finished ones included:
`stories` (done, building, approved but not started, waiting for approval, planning, no plan yet),
`parts` of approved stories and `fixes` (done, ready to merge, in progress, to do), and
`finished_last_7_days`. A story is building only once one of its parts has started. Rows also
carry `merged_at`, and `approved_by` is a name or null.
GitHub's pull request lists are read at most once a minute: the open ones and one search per
week for the last six full weeks and this one.
`team.pace` counts parts and fixes merged on the default branch per full week (Monday to Monday
UTC) for six weeks. `team.go_live` gives a date range for the parts of approved stories still to
merge, from the last three and six weeks' pace: `range`, `about` when the two agree, `not enough
history` when the oldest merged part is under three weeks old or the last three weeks merged none,
or `done`; it counts the stories with no plan yet as the unknown, and `team.sentence` says the
same in a count, not names. `team.in_progress` lists the stories and fixes in
progress (`id`, `title`, `kind`, `state`). `team.trends` counts merged pull requests per week for the team and each person
(alphabetical, no totals or ranking), split into through Forge (a `story/`, `task/` or `fix/`
branch) and around it; `team.around_forge` lists the ones merged around Forge in the last 7 days.
Both are null without GitHub, and a week capped at 1,000 results is null.
`team.needs_you` lists every item that waits on a person, oldest first, each with its `reason`,
`since` and `waited_seconds`: `approval` (a plan waiting for approval), `review loop` (a review
loop or stuck-worker choice), `worker question`, `conflict` (a merge conflict close stopped on),
`merge` (a ready pull request a human merges) and `blocked plan`, with the question or the
problem `forge next` reports in `detail`. Close and `forge work` publish
these waits to the pull request, so every machine lists the same ones; answer a worker question
with `forge work <item> --note` on any machine. `team.blocked` lists started parts and fixes
idle 24 hours or more (`stalled`) and the unfinished part the most unfinished parts wait on
(`blocks the most`), longest first, each
with `detail` and `seconds`. `team.sentence` counts both. Ask the human about each Needs you
item as `forge next` words it.
Active parts and fixes show recorded
Build, Tests, Review, CI and Merge times for their current round, with the current stage
marked. Missing times remain unknown. New clients get this at init; earlier adopted clients
get it after upgrading Forge and syncing. Cards and JSON use the same `status` and `took`
derivation; running stages include their elapsed time. Roadmap completion marks the story
and its parts finished. Finished items never stall; idle items past one day expose
`stalled`, `idle_seconds`, and `waits_on`. A story's idle clock includes its parts' activity;
a running part keeps the story active and a finished part resets its idle clock, including
a merge reported by GitHub before its commit is fetched. An older
worker round or a worker whose recorded lock is demonstrably dead is not a live run.
Live readers, workers and reviews take precedence
over a saved status, including in `forge next`. Approval history uses one display name per
Git email, honoring mailmap, and fix titles shorten at a word boundary.
Each row has `id`, `kind`, plain `title`, `stage`, `worker` (kind, model and
`started_at`, or null), `pr` (number, url and checks: pass, fail, running or unknown),
`findings` (count and titles), `round`, `stages`, `total_seconds`, `occurrences`,
`approval`, `needs_person`, and its own `next`. `needs_person` is true while the item waits on
a person, by the same decision as `team.needs_you`.
A story awaiting approval has `approval.doc`, the
absolute path to its document in its own worktree; other rows have null approval.
Task and fix rows add `time_breakdown` and `rounds`; story rows add `outcome` (null until done).
An empty board has an empty items list. Missing state shows unknown. No run start,
end, round or occurrence id is invented when its producer has not recorded one.
The last task's merged outcome marks its story done, even when the saved story
state still says approved. New clients get these views and this guide at init;
existing clients get them after upgrading Forge and running sync.
Tasks and fixes are ready only while close's clean review matches the pull request's head
(the local branch when it already holds that head) and the checks are not failing. The clean
review is this machine's receipt or the readiness close published in the pull request, so every
machine agrees. On a machine with no worktree for a ready item, its next step names the person
who started it to merge it from their machine (or, in a human-merge repo, the pull request to
merge); with the worktree here but no receipt, it is `forge close <item>`, which checks it again
and writes the receipt that `forge merge` needs. A failed
rerun shows `checks failed` with `forge work` as its next step, even after a successful
close. A running rerun or unavailable checks retain a matching receipt's readiness;
green checks alone cannot grant it. The item's next step uses the same evidence.
If the next step cannot be checked,
the row stays visible with no runnable command; check the connection and run `forge next` again.

Stages are Build, Tests, Review, CI and Merge, in that order. Each carries status,
started_at, ended_at and seconds for the current round from Forge's timing records;
unrecorded values are null. For tasks and fixes, total_seconds is elapsed time from the item's recorded start
(or first recorded activity) to now, including idle time; a finished item needs a recorded end.
Their snapshot already includes live time, so do not add a running stage's timer to it.
Worker-owned tests are separated from building in the breakdown, while close's tests and
`forge test` still appear in the Tests stage. A skipped test has status skipped. Run starts and ends
provide live worker and reader metadata; completed timing durations supply stage end
times. Values remain null where the producer has not recorded them.

`time_breakdown` separates building, own tests, reviewing, fixing findings, waiting for CI,
waiting in line, waiting for the owner and nothing running. Overlapping steps count once:
tests and recorded waits come out of the enclosing worker's time. `rounds` retains each round's
plain `line`, its finding titles, priorities and files, and its new and repeated finding counts.
Round lines number review attempts; the row's current `round` still identifies its worker turn.
Repeated means the same title and file appeared in an earlier recorded review. A missing
earlier review makes unseen findings' new-versus-repeat counts unknown. Repeats observed in the
retained history remain known even beside unseen findings whose classification is unknown.
CI lines distinguish passed, failed and gave up while queued or
running; losing contact with GitHub without a known result stays unknown.
An earlier release's failed CI timing without an explicit result also stays unknown.
Old records are not filled in with guessed findings, durations or zeroes. A known original start
can give an elapsed total even when some earlier activity is unknown; that unknown time is not
called idle and the known breakdown need not add up to the elapsed total. Gaps between legacy
timings stay unknown until complete activity recording begins. Earlier run and question events
do not establish completeness; historical questions without a recorded end stay unknown.

Quote the item's round lines when explaining a long run, then quote the relevant breakdown
categories rather than adding overlapping stage timers. The board page shows these same
details. The pull request's short **How it went** section comes from the same logs and keeps
earlier findings after later reviews. Forge keeps the pull request body in an agent squash
merge; when the human merges, keep this section in the squash commit body too. New repos get
this guide and the recording behaviour at init; previously adopted repos get them on upgrade
and sync. Their earlier unrecorded history remains unknown. If a fresh clone or missing local
logs cannot reconstruct already published measurements, How it went retains them and shows
the current checkout's observations separately. Quote each snapshot separately; do not add
their totals, because their intervals may overlap.

Quote the item's round lines when explaining a long run, then quote the relevant breakdown
categories rather than adding overlapping stage timers. The board page shows these same
details. The pull request's **How it went** section carries intervals, review rounds (including
clean reviews), and waits with their ends. The shared record has a fixed size: while it is over, the oldest
detail of any kind (round lines, intervals, then raw events such as repeated CI waits) folds into
one "Rounds 1–N" line of totals and finding counts, oldest first; the newest round keeps its own numbered line,
and its folded retries add to it. Free text in each entry is cut to 300 characters, and a round
too big on its own, such as a huge review, folds whole into its line. Live progress stays local. So a
long item stays inside GitHub's body limit, and folding never changes its total time. Close and merge retain observations from other
checkouts and recompute repeated findings and overlapping time. The board reads this shared
record alongside local observations; `source` says which it had. A GitHub merge ends the last
wait at its merge time and names its merger. Story time counts each instant once: working when
any part or recorded plan read is working, waiting when none is working and any is waiting,
otherwise unknown. Inside a part's folded time range, the story's split between working and
waiting is approximate; the totals stay exact. Human times use rounded plain units; JSON keeps raw seconds. Rebuilt history
keeps its label and missing evidence remains unknown. New repos get this at init; existing
repos, including earlier adoptions, get it on upgrade and sync.
Worker questions and their answers refresh an existing pull request's record; a question before
its first pull request stays local. A first-close merge conflict opens the pull request so its
owner wait travels too, and resolving it records the wait's end.
Resuming work ends a published merge wait even when another checkout started it. History
refreshes retain the pull request's readiness; close publishes readiness for a newly checked head.
Board and next reads use the current pull request history and head; cached checks apply only
to the head they describe.
Questions on older pull requests without local publication evidence stay local.
Every pull request body stays within GitHub's size limit. Forge leaves tool-command prose out
of the shared time record, shortens duplicated and advisory detail before the contract, and
says plainly when it shortened anything. Exceptionally large time histories retain recent
evidence and current readiness; omitted time stays unknown. Full contracts and proof stay in git.
Items report working, waiting and unknown seconds alongside their detailed categories. An
unfinished story's runway continues through now, including unknown time after its last read
or recorded part activity; a read without a duration establishes a date, never guessed work.

Live rows add `activity` (status and a running action), `idle_since` and `stalled`
after 24 idle hours. A recorded worker adds tool, model, effort, round, start,
elapsed seconds and its latest tool step; close's live `tests` adds elapsed and
done/total where the runner reports progress. `gates` has plan_read, review and ci,
each with status; blocked reviews add count and running CI adds elapsed seconds.
PR failures list job and cause (timeout or failed); findings add items with title
and priority and a dismissed count. Both views' `events` list the last 20 run,
review and question records as time, item and one plain line, newest last.
Queue places stay absent until the shared lane entries ship.

The newest 25 open pull requests get checks in one GitHub request, cached for 60
seconds in the shared Git directory. Older pull requests and unreachable GitHub
show unknown checks. Required checks, including matrix variants, must succeed;
skipped or neutral required checks show fail, while optional ones count as passed.
A failed check occurrence keeps GitHub's own identity:
`check-run:<databaseId>:<completedAt>` or `status:<id>`. A rerun with a later
completion is a new occurrence. Each occurrence has id, kind and plain title;
run completions, undismissed review findings (including advisory findings) and unanswered
worker questions retain the ids in Forge's event records. Advisory occurrences do not
change the merge gate. Readiness uses the clean review's id plus the current head
commit. Runs that start and finish between board refreshes still appear as completions.

Both views' `next` contains `command`, `line` and `step`. Command is the first Next line
only when it is one runnable Forge command without a placeholder or alternative;
otherwise it is null. Line carries the plain current state from the text report. Step is
the first Next line's text even when it is not one runnable command, or null without one.
Release notices appear in the text output and never replace the machine view's state line.
Use each board row's next step for that item, never another
item's step. Machine views do not grant approval or permission to merge.

The shared mod contract fixture is `tests/fixtures/board.json`; command coverage
in `tests/test_machine_views.py` checks both views against it.

## Claude Code plugin core

The Claude Code mod reads Forge's machine views, runs `forge` commands and draws;
it never edits repo files or replaces the commands' approval and merge rules.
All its consumers share one snapshot. On load, then every 10 seconds, one refresh
runs `forge next --json` and `forge lanes --json` together. The next output also
supplies the board rows, so the pane reads them once per refresh.
If that Forge has no lanes command, lane data is absent. A due refresh is skipped
while the previous one runs, rather than queued. There is no extra fetch on `/forge`.
Drawing ticks advance live timers every second without fetching state.

A failed or malformed refresh, or a command taking over 60 seconds, keeps the
last good rows and adds a dim `Couldn't refresh: <first line of the error>`.
It retries on the next tick. Only a non-zero command result containing
`unrecognized arguments: --json` shows
`This repo's Forge is too old for the pane: upgrade Forge here.`
Other failures use the normal refresh error. The board command owns the
60-second GitHub checks cache described above; a check changing without a local
edit appears on the next refresh after that cache expires. Unknown checks stay
unknown, including when GitHub is unreachable.

## Installing the mod

`forge sync` installs or updates the mod from Forge's latest release at user scope,
one per machine, independently of each repo's pinned Forge version. It needs
Claude Code v2.1.287 or newer on PATH. When the marketplace is missing, sync runs
`claude plugin marketplace add knacklabs/symphony-forge`, then always runs
`claude plugin marketplace update forge`. It runs
`claude plugin install forge@forge --scope user` for a new user install, or
`claude plugin update forge@forge --scope user` for an existing one.
Sync writes no repo files for the mod; Codex's setup and workflow are unchanged.

Without `claude`, sync skips the mod. A failed install or update (including no
network or old Claude Code) prints one warning line and sync still succeeds;
run `forge sync` to retry. `forge doctor` warns when Claude Code is missing or
older than v2.1.287 and keeps exit status 0. In a running session, use
`/reload-plugins` or restart to load the updated mod. Desktop's WSL sessions load
no plugins; use the `forge` command there.

The mod runs `forge` from PATH with argv and no shell, in the session's repo root.
It does not change the repo's pin. If the pane or strip says that repo's Forge is
too old, upgrade Forge in that repo; other refresh errors follow the core's retry
behaviour above. Sessions without the mod keep using the commands as today.

## Approving with the pane

The pane has no Approve button: Claude Code's mod API cannot supply the story's exact text
to its native plan-approval prompt. Use Plan Mode and the story doc `forge next`
names, following Planning a story below. The existing approval hook and its trust
checks are unchanged. Plan Mode remains the approval path in Claude Code, Codex,
the VS Code chat panel and sessions without the mod; installing the mod changes
no approval rule.

## The pane and strip

Type `/forge` at any width, including 80 columns, to open and focus the pane.
The mod requests it at interactive session start too; Claude Code places it
automatically at 144 columns, or 110 after the person has opened it once.
The strip below that wide-screen threshold ends with `/forge for the board`.
The pane's Board tab, on the terminal and the Desktop app's Code tab alike, opens
with one summary line, such as `3 in progress · 1 needs you · 2 stuck · go-live Oct 20`.
Each part shows only when the board's `team` fact behind it is known and not zero; when
none of them applies, the line counts the rows the tab shows in its own group words instead,
such as `1 moving · 2 ready to merge · 3 waiting`; an empty board says only `Nothing in progress.`. An older Forge with no `team` shows no summary line. Below it come the board's
own sentence (`team.sentence`) and its labelled totals, one line per kind, such as
`Fixes — Done: 0; Ready to merge: 0; In progress: 1; To do: 0`, words built from
`team.counts`. Groups follow in this order, each only when it has items, and each in the board's own
order: NEEDS YOU (one row per `team.needs_you` entry, oldest first, with how long it has waited,
such as `waiting 3h`), STUCK (one row per `team.blocked` entry with its reason in words and its
age, such as `1 unfinished part waits on it · 2d`, and the longest stall in days), MOVING (the board's In progress, `team.in_progress`, except what is ready to merge;
a running item shows its current stage and how long, such as `Review running · 12 min`),
READY TO MERGE (the rest of `team.in_progress`, each saying Ready to merge, with the checks in words when known, and its merge
step; an item merged from another machine shows `forge next`'s line naming who merges it), then a
folded count of the work waiting or not started (planned stories and fixes not started), opened with a native button to the same rows. Each item shows its plain title, the story key small
beside it, one line of state in words and, where there is something to do, its next step
(`next.step`) after `→`. At most five rows show per group, then `and N more · forge board for all`.
An older Forge without the `team` lists draws the same groups from each row's `needs_person`,
stalled, running and ready flags, and shows no sentence or totals.
Outside those totals, the pane never shows zero counts, unknown times, raw timestamps, priority codes or
dismissed counts; findings read `Review found 3 problems`. Dates are short (`Oct 5`) or
relative (`12 min`, `8 days`), and every time rounds as the board's do (`2m`, never `1m 30s`). Stage chains, round lines and the time breakdown stay on
the board page. An empty board says `Nothing in progress.` `/forge` always returns the
same lines as text, as well as opening the pane. Where mods draw nothing (the VS Code
chat panel, `claude -p` and Remote Control from a phone or claude.ai), that text is the
status reply. It uses the last completed snapshot, including any refresh error. Until a
first refresh succeeds, the pane, the strip and `/forge` say `Loading Forge…`, or
`Couldn't refresh: <first line of the error>` once that refresh failed.

The strip above the prompt uses at most three lines. Its first line shows
`Agents N/M (W waiting) · Tests N/M (K waiting) · <running item or idle> · 1: <next command>`.
It also shows a recorded current worker step. The other lines show up to two active items
from this repo, each with Build → Tests → Review → CI → Merge, its round and total
time. A third active item replaces the last line with `+N more · /forge for all`.
Finished stages show ✓ and their duration, the current stage ● and a live timer,
and failed stages ✗ in red. Unreached stages have only their name; skipped tests
show `Tests –`. Symbols carry the meaning without colour. The total uses the elapsed-time
snapshot, which includes live and idle time without counting concurrent stages
twice. At widths under 80 columns it is one line: running and waiting counts, the first
active item's current stage and time, its total and the next step; without lane data,
the first line is only the next step; the narrow strip has no item or lane summary.

Press `1` on an empty prompt when Claude is idle to run the displayed next command
as the user. Before submitting, the mod re-reads `forge next --json`: if the command
changed it redraws and runs nothing. A failed re-read submits nothing and toasts
`Couldn't check the next step: <reason>`; a failed submit toasts
`Couldn't run the next step: <reason>`. A null command or busy Claude has no hotkey
and shows the plain next-step line instead. Typing into a nonempty prompt stays typing.

## Events

The mod starts a session turn for new review findings, failed checks, a pull request
ready to merge, worker questions and finished runs. Progress only updates the pane:
starting a run or running checks never asks the agent for a status turn.
Each event line names the plain item title, what happened and that item's own next command,
or `forge next` when there is no runnable command. When the turn arrives, act on it
straight away through Forge's commands: resolve findings with evidence or send a
worker round, follow a failed check's next step, close finished work, and merge ready
work only when allowed. Answer a worker question with
`forge work <item> --note "<answer>"`; a choice the human owns still goes to them.
Do not build another polling or watcher loop for an interactive mod session.

Forge's occurrence ids distinguish events, never their text: review results, run
ends and questions get fresh ids; CI completions use the workflow id and head commit.
Failed checks outside a workflow use GitHub's id and completion time,
failed commit statuses use their own id, and readiness uses the review id and head commit.
The same question in another round or a check failing again after a later completion
therefore gets another turn, even if its wording is unchanged. A run that starts
and finishes between refreshes still has its completion occurrence.

Seen ids are stored for the repo root and session id together, so two sessions
consume events independently. At session start or reload the current ids become
seen without starting a turn. Several changes, including those found while Claude
is busy, are combined in one turn after the current turn ends, one line per event.
At delivery, each line uses the item's current next command. Events for items that
have since merged are dropped. A CI completion names the workflow and its result,
once per workflow and commit.
A failed submission leaves them unseen for the next refresh to retry; a successful
one is not repeated. Only interactive sessions on terminal or Desktop receive
event turns, and only for their own repo. Forge-started workers, readers and
reviewers have `FORGE_WORKER=1` and never act on events. Headless sessions receive
no event turns. Codex and sessions without the mod keep using `forge next` and the
existing command flow.

## Handoff

`.git/forge/handoff.md` in the main checkout, shared by every worktree, carries your state across
a compaction. Before each compaction Forge rewrites its current-state part from `forge next` and
keeps everything under `## Decisions and lessons`. Add one line there at each milestone: a story
approved, a task merged, a decision the owner made, a lesson learned or a mistake you won't
repeat. After a compaction or in a new session, read it first. The file is local and never
committed.

## Coaching

The first time each of these happens for a person, add one plain sentence saying what just
happened and what they can do next. Say it once, then never repeat it, and never name commands
unless they ask. Note each one in the handoff so a new session doesn't repeat it.

- A story plan shown for approval: "This is the plan in short; you can approve it as it is or tell me what to change."
- A cold read finding: "A fresh reader found a gap in the plan, which I'm fixing; you can weigh in on the fix or wait for the next read."
- A part starting: "A worker is building this part on its own copy; you can keep planning meanwhile."
- A pull request ready: "This part passed its tests and review; you can look it over before it merges."
- A merge: "This part is now in the main code; you can try it there or pick what comes next."
- A prototype demo: "The customer has seen it working; you can tell me what they did and said to shape the next round."
- Sign-off: "The customer approved the prototype; you can now choose the first real story to plan."

## New directions

Grill any request with more than one reaso

[…] pełny plik w paczce .zip
Files in this package (4)
  • SKILL.md 159 KB
  • fde.md 9 KB
  • migrate-skill.md 5 KB
  • standards.md 22 KB

Versions

RepositoryScoreLicence
This page · knacklabs/symphony-forge91MIT
aimi-so/aimi-engineering-plugin100MIT
claudemods/context-forge100MIT
cwinvestments/memstack100MIT
MohammedAtya/guardrail-forge100MIT
faizanio/FORGE100MIT
thecrazybob/claude-code-plugins100MIT
floka-as/floka-marketplace100MIT

Identical content appears in 2 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 161205693b4b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100forge-implement
    Implement a feature or fix from an Issue, plan file, or free-text description, following project standards. Use when the user wants to start working on an Issue, implement a feature, or fix a bug — stops after opening the PR (use forge-ship to also run review).
  • 90st-ship
    Takes a change all the way from code to a merged pull request without supervision: build it, prove it, review it, file the PR, watch it and merge it. Use when the user says ship it, send it all the way, merge when green, or /st-ship.
  • 90ship
    Take a change in this repository from request to a merged pull request with no person in the loop. Use for every change in this repository, and when the user says "ship".
  • 95forge-land
    Decide what a green pull request needs from a human: check it is mergeable, green, addressed and exercised, get a fresh-context risk verdict on the head commit, write it into the PR as a ## Risk section, and report merge-ready or review-ready. Merges a low-risk PR only when the…
  • 100forge-design
    Tyler Forge design system expert. Trigger when the user mentions Forge, Forge components, Forge blocks, @tylertech/forge, forge-tailwind, tyler-icons, forge-scaffold, forge-card, forge-app-bar, forge-table, forge-dialog, forge-drawer, forge-list, forge-field,…
  • 95next
    Implement the next Approved story from the board - slot, tests, code, check, PR, auto-merge. Use when asked to pick up the next story, implement an approved spec, or start an approved story. Writing the spec for a Ready story is /spec.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.