에이전트 엔지니어링. 하나의 작업을 하나의 사이클로.Agent engineering. One task, one cycle.
ask·plan → execute → retro → done.
22개의 fg- 스킬로 만든 루프형 워크플로우. 계획은 대화로 갈고, 실행은 워크플로우로 돌리고, 회고는 문서로 남깁니다.A loop-style workflow built from twenty-two fg- skills. Plans are sharpened in conversation, execution runs as a workflow, and retros stay in the docs.
The Loop
한 스킬이 끝나면 다음으로 가는 길을 고정 4행 핸드오프 표로 알리고 멈춥니다 — 그 걸음을 밟는 것은 fg-next의 몫입니다. fg-done이 작업을 봉인하면 같은 작업은 두 번 돌지 않습니다.When one skill finishes, it states the way to the next as a fixed four-row handoff table; run fg-next to take that step. Once fg-done seals a task, the same task never runs twice.
새 작업이면 fg-ask로 다시 시작 · 다른 결과가 나오면 재-grillingNew task? start again at fg-ask · diverged? re-grill
Skill catalog
루프의 진입점. 도메인·용어·결정을 상대로 계획을 갈아 backlog와 CONTEXT/ADR로 남깁니다. "forge로 시작하자", "새 작업"으로 트리거.The loop's entry point. Grills the plan against domain, terms, and decisions, leaving it in the backlog and CONTEXT/ADR. Triggers on "start with forge", "new task".
계획을 워크플로우로 실행. 미실행 계획이 하나면 즉시 실행, 여러 개면 우선순위 선택 목록(마지막 옵션 "Run all")을 띄웁니다.Runs the plan as a workflow. One unexecuted plan runs immediately; several show a priority-sorted selection (last option "Run all").
run.md·plan·executed를 읽어 배움을 CONTEXT/ADR/retro로 승격하고 다음 탐구를 제안합니다.Reads run.md/plan/executed, promotes learnings to CONTEXT/ADR/retro, and suggests the next inquiry.
회고를 확인하고 STATUS를 done으로 닫아 아카이브. 활성 상태를 비우고 루프를 닫습니다. 기계적 봉인은 결정론 스크립트(forge-done.sh/.js)가 처리합니다. all 모드는 이미 실행된 작업을 일괄 봉인합니다.Confirms the retro, closes STATUS as done, and archives. Empties active state and closes the loop; the mechanical seal runs as a deterministic script (forge-done.sh/.js). all mode batch-seals already-executed tasks.
코드베이스를 병렬 서브에이전트로 매핑해 .forge/codebase/에 저장. grilling이 코드를 다시 탐색하지 않게 합니다.Maps the codebase with parallel subagents into .forge/codebase/, so grilling reads a map instead of re-exploring.
사소한 작업 전용 경량 레인. 가볍게 grill 후 형식 산출물 없이 바로 실행. 커지면 fg-ask로 넘깁니다.Lightweight lane for trivial tasks. Grills lightly, then runs directly with no formal artifacts. Bails to fg-ask if it grows.
읽기 전용 리포터. .forge/를 훑어 모든 작업의 현재 위치와 다음 한 걸음을 출력. 아무것도 쓰지 않습니다.Read-only reporter. Surveys .forge/ and prints where every task stands plus the single next step. Writes nothing.
fg-status의 상태 머신으로 다음 한 걸음을 도출해 실제로 실행. all 모드는 백로그가 빌 때까지 몰아붙입니다.Derives the next step via fg-status's state machine and runs it. all mode drives until the backlog is empty.
goal 주도 한정 재계획 루프. 기계 검증 가능한 정지 조건이 통과할 때까지 run → UAT → 봉인을 자동 주행하고, 실패 체크는 상한 내에서 fix-forward로 재계획합니다.Goal-driven loop with bounded replan. Drives run → UAT → seal until machine-verifiable checks pass, auto-generating fix-forward work for failing checks within a cap.
통합 설정 진입점. .forge/config.json의 여섯 키(simple·eco·tdd·driveCommit·driveCommitMessage·defaultBranch)를 읽고 씁니다. simple을 켜면 fg-run이 검증 후 같은 턴에 봉인까지 잇습니다(검증 게이트는 불가침). 옛 키별 토글 스킬을 대체합니다.Unified settings surface. Reads and writes the six .forge/config.json keys (simple·eco·tdd·driveCommit·driveCommitMessage·defaultBranch). With simple on, fg-run verifies then seals in the same turn (the verification gate stays inviolable). Replaces the former per-key toggle skills.
git merge 후 브랜치의 .forge/branch/<b>/를 .forge/로 통합(결정론 스크립트, AI 없이 CI 게이트 가능). 시간ID ADR 이동(충돌 시 다음 글자, 재번호 없음)·CONTEXT 병합·done 이력 접기. git은 실행하지 않음.After a git merge, folds a branch's .forge/branch/<b>/ into .forge/ (a deterministic script, usable AI-free as a CI gate). Moves time-based ADR IDs (collision → next letter, no renumber), merges CONTEXT, folds done history. Never runs git.
낡거나 대체된 ADR을 활성 집합에서 은퇴시켜 retired/로 이동. 번호는 그대로, 삭제는 없음. 승인은 사람이.Retires stale/superseded ADRs from the active set into retired/. Numbers stay, nothing is deleted. A human approves.
fg-run과 fg-learn 사이 선택적 적대적 검토. 결과가 틀렸다고 가정하고 6개 렌즈로 병렬 검증해, 수정이 필요하면 fix-forward 계획을 만듭니다.Optional hostile review between fg-run and fg-learn. Assumes the result is wrong and verifies across six lenses in parallel; fix-needed findings become a fix-forward plan.
.forge/ 상태 계약과 문서·매니페스트 정합을 훑는 읽기 전용 무결성 검사(결정론 스크립트, AI 없이 CI 게이트 가능). 고아 파일·깨진 STATUS·버전 드리프트를 심각도와 함께 보고합니다.Read-only integrity check of the .forge/ state contract and docs/manifest sync (a deterministic script, usable AI-free as a CI gate). Reports orphaned files, broken STATUS, and version drift with severity.
읽기 전용 사용법 도움말. fg-help는 forge 스킬 전체를 루프 4단계 + 루프 밖 유틸리티로 그룹핑한 개요를, fg-help <명령>은 개별 스킬의 4줄 상세를 냅니다. 각 SKILL.md의 description을 단일 소스로 읽어 사용자 언어로 렌더합니다.Read-only usage help. fg-help prints an overview of every forge skill grouped by the four loop stages plus the outside-the-loop utilities; fg-help <command> prints a 4-line detail for one skill. It reads each SKILL.md's description as the single source and renders in your language.
봉인되지 않은 미완 작업(백로그·활성·executed·멈춘 goal 루프)을 위험도와 함께 보여주고, 하드 삭제 또는 dropped/ 보관 중 선택하게 합니다.Shows unsealed, incomplete work (backlog/active/executed/halted goal loop) with a risk level, then lets you hard-delete or archive to dropped/.
대화형 그릴링으로 프로젝트에 반복되는 역할을 찾아 .claude/agents/<role>.md 카드를 생성합니다. 세션 재시작 후 fg-run이 매칭 role을 dispatch합니다.Finds recurring project roles by conversational grilling and generates .claude/agents/<role>.md cards. After a session restart, fg-run dispatches the matching role.
forge 루프 진행 상태를 statusline에 두 모드로 표시. 방법 1(append)은 기존 statusLine을 대체하지 않고 아래 별도 줄로 wrapping, 방법 2(merge)는 daleseo식 시스템 정보(모델·디렉터리·git·사용량 바)와 forge 진행을 한 스크립트로 출력합니다.Shows forge's loop progress in your statusline in two modes. Method 1 (append) wraps your existing statusLine as an extra line below instead of replacing it; method 2 (merge) installs a unified script rendering daleseo-style system info (model·dir·git·usage bars) alongside forge progress.
브라우저 시각 컴패니언. 로컬 서버가 목업·다이어그램·A/B 비교를 탭에 띄우고, 지원 호스트에서는 화면의 확정 버튼만으로 답이 도착하며, 그 외 호스트에서는 확정 뒤 터미널 입력 한 번이 필요합니다.Browser visual companion. A local server shows mockups, diagrams, and A/B comparisons in a tab; on supported hosts the confirm button delivers your answer directly; other hosts need one terminal turn after confirmation.
안개 속 작업의 결정 대기열. 목적지를 정한 뒤 무엇을 결정해야 하는지 캐내 .forge/agenda.md에 담고, 한 번에 하나씩 해소합니다. 찾는 건 에이전트, 답하는 건 당신.A decision queue for work still in fog. Pins a destination, digs out what must be decided into .forge/agenda.md, and resolves them one at a time — the agent finds them, you answer.
코드베이스 보안 감사. cloudflare 방법론을 vendoring해 공격 유형별로 병렬 탐색하고, 산출물은 리포 밖에 남겨 취약점 목록이 커밋될 경로를 없앱니다. 심각도 게이트 통과분만 당신 승인 후 plan이 됩니다.A codebase security audit. Vendors cloudflare’s methodology to hunt in parallel by attack class, and keeps artefacts outside the repo so a vulnerability list has no path into a commit. Only severity-gated findings become plans, on your approval.
어려운 버그의 대화형 진단. mattpocock 방법론을 vendoring해 red를 내는 피드백 루프를 세우고 재현·최소화한 뒤, 가설을 당신과 함께 순위화합니다. 진단만 하고 수정은 루프에 돌려보냅니다.Conversational diagnosis for hard bugs. Vendors mattpocock’s methodology to build a red-capable feedback loop, reproduce and minimise, then rank the hypotheses with you. It only diagnoses — the fix goes back to the loop.
Which one holds the work
한 단계보다 오래 사는 일을 담는 스킬이 셋이고, 셋 다 대화로 시작하기 때문에 헷갈리기 쉽습니다. 다른 것은 그 대화가 무엇을 못 박느냐입니다.Three skills hold work that outlives a single step, and they're easy to confuse because all three open with a conversation. What differs is what that conversation pins down.
fg-agenda는 계획의 상류에 있고 · fg-ask가 계획을 만들고 · fg-loop은 계획 하류를 주행합니다.fg-agenda sits upstream of the plan · fg-ask makes the plan · fg-loop drives past it.| 축Axis | fg-ask | fg-loop | fg-agenda |
|---|---|---|---|
| 위치Position | 루프 ① 단계loop stage ① | 루프 밖 — L3 무인 주행outside — L3 unattended drive | 루프 밖 — 계획 유틸리티outside — planning utility |
| 첫 대화가 못 박는 것What the opening conversation pins down | Work slices + 완료 기준work slices + completion criteria | 기계 검증 가능한 정지 체크 + 재계획 상한machine-verifiable stop checks + replan cap | 목적지 + 열린 질문a destination + the open questions |
| 담는 파일File it holds | backlog/<slug>.md |
loop.md |
agenda.md |
| 답하는 사람Who answers | 당신, 모든 질문you, every question | 없음 — 무인으로 돕니다nobody — it runs unattended | 당신, 모든 질문 (에이전트는 찾기만)you, every question (the agent only finds them) |
| 끝나는 조건Done when | 실행 가능한 계획이 나오면an executable plan exists | 체크 전부 통과 (기계 판정)every check passes (machine verdict) | 더 결정할 것이 없으면 (판단)nothing is left to decide (judgment) |
| 진행할 수 없을 때When it can't proceed | 다음 질문을 합니다asks you the next question | 벽에서 멈추고 맥락과 함께 넘깁니다halts at a wall, hands back with context | 안개(fog)에 적고 넘어갑니다writes it into fog and moves on |
| 수명Lifespan | 한 세션one session | 여러 세션 — goal 충족 시 loop.md 삭제many sessions — deletes loop.md on goal met |
여러 세션 — 비면 agenda.md 삭제many sessions — deletes agenda.md when empty |
선택 기준 — 지금 무엇을 댈 수 있나?The selection test — what can you produce right now?
대략이라도 Work slices를 댈 수 있다I can name the work slices, even roughly
이것이 기본이고, 나머지 둘이 예외입니다.This is the default; the other two are exceptions.
"완료"를 통과/실패하는 명령으로 표현할 수 있다I can express "done" as commands that pass or fail
체크가 전부 통과할 때까지 무인으로 주행합니다.It drives unattended until every check passes.
둘 다 못 하고, "무엇부터?"의 정직한 답이 "뭘 결정해야 하는지도 모르겠다"다Neither — and the honest answer to "what first?" is "I don't even know what has to be decided"
안개가 없으면 스스로 fg-ask를 가리킵니다.With no fog, it points at fg-ask itself.
셋은 경쟁하지 않고 이어집니다 — 의제는 질문을 하나씩 그릴링으로 해소하고, 결정이 빌드 가능해지는 순간 그 줄은 백로그로 떠납니다. 그리고 fg-loop은 fg-agenda의 거울상입니다 — 기계 정지 조건으로 무인 주행하는 쪽과, 판단 정지 조건으로 사람이 답하는 쪽. 그래서 둘이 하나가 아니라 둘입니다.They chain rather than compete — an agenda resolves one question at a time by grilling, and the moment a decision makes something buildable it leaves for the backlog. And fg-loop is the mirror image of fg-agenda: unattended with a machine stop condition, versus human-answered with a judgment one. That is why they are two skills and not one.
The two pillars
Dynamic Workflow는 실행 중 사용자 입력을 받을 수 없습니다. 그래서 질문-대-질문으로 계획을 갈아내는 grilling은 워크플로우 바깥, 대화 안에서만 일어납니다.A Dynamic Workflow cannot take user input mid-run, so question-by-question grilling happens only outside the workflow, in conversation.
계획에서 벼려진 용어는 실행의 기준이 되고, 회고의 배움은 다음 계획의 출발점이 됩니다. CONTEXT.md · ADR · retro log에 쌓입니다.Terms forged in planning become the standard for execution, and retro learnings become the starting point of the next plan. They accumulate in CONTEXT.md · ADRs · the retro log.
Install
Claude Code 세션에서 GitHub 마켓플레이스를 추가하고 플러그인을 설치합니다.In a Claude Code session, add the GitHub marketplace and install the plugin.
스킬은 skills/<name>/SKILL.md에서 자동 발견됩니다 — 별도 설정 없음. 설치 후엔 fg-ask를 부르거나 "forge로 시작하자"라고 말하면 루프가 시작됩니다.Skills are auto-discovered from skills/<name>/SKILL.md — no extra config. After installing, call fg-ask or say "start with forge" to begin the loop.
간단한 사용법How it works
fg-ask를 부르거나 "forge로 시작하자", "새 작업"이라고 말하면 대화형 grilling이 계획을 갈아냅니다.Call fg-ask or say "start with forge" / "new task" — conversational grilling sharpens the plan.
fg-run이 계획을 Dynamic Workflow로 실행. 끝나면 계획의 목표에 대해 UAT를 돌려 STATUS.md에 검증 결과를 기록합니다.fg-run runs the plan as a Dynamic Workflow. When done, it runs a UAT against the plan's goal and records the result in STATUS.md.
fg-learn이 배움을 문서로 승격. 사소하고 편차가 작으면 회고를 건너뛸 수도 있습니다.fg-learn promotes learnings to docs. For a trivial, low-divergence task the retro may be skipped.
"작업 완료"라고 하면 fg-done이 검증·회고를 확인하고 done/으로 아카이브 — 같은 작업은 다시 돌지 않습니다.Say "seal" and fg-done confirms verification and retro, then archives to done/ — the same task never runs again.
"forge status"로 지금 위치를, "forge next"로 다음 한 걸음을 바로 실행. "이거 빨리 해줘"엔 fg-quick."forge status" shows where you are; "forge next" runs the next step. For a quick one-off, fg-quick.
Shared state
모든 상태가 파일로 전달되어, 각 단계를 따로 불러도 흐름이 이어집니다. 단일 .forge/ 디렉터리가 휘발성 루프 상태와 git이 추적하는 영구 문서를 모두 담습니다.State is passed through files, so the flow continues even when stages are invoked separately. A single .forge/ directory holds both the volatile loop state and the git-tracked permanent docs.
하나의 plan.md = 하나의 run.md = 하나의 봉인. 백로그가 여러 개면 fg-run이 선택 목록을 띄웁니다.One plan.md = one run.md = one seal. With several in the backlog, fg-run shows a selection.
run → verify → learn → done. verified:가 통과 상태여야만 fg-done이 봉인합니다.run → verify → learn → done. fg-done seals only when verified: is a passing value.
기본 외 브랜치는 .forge/branch/<branch>/에서 동작. merge 후 fg-merge가 통합합니다.Non-default branches operate under .forge/branch/<branch>/. After a merge, fg-merge folds them in.