forge-flow

name	forge-flow
description	Load when the user starts a new session on an ongoing effort — fresh chat, 'let's continue', 'pick up where we left off', or the first turn of any working session.
source	https://raw.githubusercontent.com/weselben/RooForge/main/skills/forge-flow/SKILL.md

Forge Flow

Forge Flow is the session-start bootstrap that runs before forge step 1. It prepares the work surface (branch) and the contract (goal), then hands off to forge.

The goal is long-living, not per-session: it covers the full wayfinder map, which may take months to resolve. The goal is the contract; forge steps are the proof.

Steps

1. Detect map

Three cases:

• Map URL or number provided — load it. The map defines the scope of the contract.
• Map exists in tracker — query for an open wayfinder:map issue. Load it if found.
• No map — hand off to forge step 1, which invokes wayfinder chart mode. Goal is written in step 4 with placeholder map reference.

Completion criterion: agent knows whether the map exists, and if so, its URL/number.

2. Name the feat branch

Branch name follows feat/<slug>.

Derive the slug from the map name when a map exists, else from the user's first turn:

• Map "Idempotency keys for payment endpoint" → feat/idempotency-keys
• Map "Auth JWT refactor" → feat/auth-jwt-refactor
• No map, user says "fix cache race" → feat/cache-race-fix

If the map already has an associated feat/* branch, reuse it. The lookup follows the git-issue-tracker "Branch association" convention: read the map body for a ## Feat branch heading; else git branch -a --list "feat/<slug>*"; else gh pr list --head "feat/<slug>" --state open. Otherwise create a new feat/<slug>.

Completion criterion: a valid feat/<slug> name is determined, or an existing one is identified.

3. Create or switch to the feat branch from main

Always cut from main — never from another feat, hotfix, or chore branch.

git checkout main
git pull
git checkout -b feat/<slug>   # or: git checkout <existing-feat-slug>

Completion criterion: git branch --show-current returns the feat branch; git merge-base --is-ancestor main HEAD is true.

4. Write the contract goal

The goal is the full map contract, STE100-formulated. It covers the entire wayfinder map — every ticket to resolve, every decision to lock — not just today's session work. A session may resolve one ticket; the goal tracks them all.

Create with CreateGoal (if available), objective:

Complete wayfinder map "<map-title>" (map: <map-url-or-number>) — load forge skill (mandatory while goal is active). Map every open ticket, resolve every ticket, integrate via forge flow, merge PR, user merges. Goal is long-living: tracks the full map across all sessions until user merges.

The goal contains three mandatory fields:

1. Forge skill reference — the literal phrase load forge skill (mandatory while goal is active) ensures forge reloads on every turn where the goal is in scope.
2. Map URL or number — anchors the contract to a concrete tracker artefact. Include it even when chart mode creates the map mid-flow; update the goal once the map exists.
3. STE100 prose — short sentences, one meaning per word, no hedge. The goal text is re-injected into the agent's context on every turn; ambiguity compounds.

If the harness supports goal fields beyond objective (e.g. description, metadata), put the full STE100 expansion there — the map destination, the ticket summary, the standing constraints — so the agent reads the contract at full resolution when the goal enters scope.

Update rule: the goal is immutable from the moment it is written. Additions (new tickets, scope changes, map URL corrections) go into the goal's description or metadata, never into the objective. The objective is the contract; everything else is expansion.

Completion criterion: goal exists and is active; objective contains load forge skill (mandatory while goal is active) and the map URL/number (or explicit placeholder if no map yet).

5. Hand off to forge step 1

Tell the agent: "Continue with forge step 1 — load or chart the wayfinder map."

Completion criterion: forge skill is invoked; no further action in this skill.

Rules

• Always from main. Never cut a feat branch from another dev branch.
• One goal per map. If a goal already exists for the map, reuse it (do not create a duplicate). Forge Flow only writes the goal when none exists.
• Goal is the contract. Treat the goal text as immutable after creation. Expand in metadata or description, never rewrite the objective.
• STE100 prose. Goal text re-injects on every turn; ambiguity compounds. Short sentences, one meaning per word.
• No chat before step 1. Forge Flow is silent unless it must ask the user for the feature name (when the first turn is ambiguous and no map exists).

Boundaries

Forge Flow does not:

• Load caveman or wayfinder (forge does that)
• Chart the map or resolve tickets (forge step 1–2)
• Plan, work, verify, review, resolve (forge step 3–8)

It only prepares the work surface and the contract, then hands off.