[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DYDAWZVG23SR4B8ETHDQAF":3,"skill-same:01M6DYDAWZVG23SR4B8ETHDQAF":77},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":6,"ownerHtmlUrl":54,"ownerBlogUrl":55,"ownerDescription":6,"updatedAt":56,"install":57,"resources":70},"01M6DYDAWZVG23SR4B8ETHDQAF","forge",null,"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.","knacklabs\u002Fsymphony-forge","knacklabs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F304408816?v=4","01M6DY9T9G3AQ6DM846DVTBD2Y","KnackLabs","01M6DY9TDZY6RJMQD6ZM773ZD3",10,"MIT","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002Fsrc\u002Fforge\u002Ftemplates\u002Fskill.md",[],[5,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"use","when","request","which","close","add","human","next","task","do","build","Story","roadmap","spec","fix","board","check","decision","plan","save","start","pull","run","pull request","setup","2026-11-10 10:12:30",false,"---\nname: forge\ndescription: 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.\n---\n\u003C!-- Generated by forge sync. -->\n\n# Forge\n\nStart with `forge next`. It says where things stand and gives the exact next command.\n\n| The human says | Run |\n|---|---|\n| \"What now?\" | `forge next` |\n| \"Show me progress\" | `forge board` |\n| \"Plan a new story\" | `forge story new \u003CKEY> \"\u003Ctitle>\"` |\n| \"Read the plan cold\" | `forge read \u003CKEY>`, or `forge read \u003Cslug>` for a spec |\n| \"I've amended it\" | `forge read \u003CKEY>` again, for the next round |\n| \"Start this task\" | `forge task start \u003CKEY>\u002F\u003CTASK>` |\n| \"Fix this small thing\" | `forge fix start \"\u003Cwhy>\" --done \"\u003Cdone when>\"` |\n| \"Name this fix\" | `forge fix start \"\u003Cwhy>\" --done \"\u003Cdone when>\" --slug \u003Cname>` |\n| \"Change this fix's Done-when\" | `forge fix amend \u003Cfix> --done \"\u003Cdone when>\" --because \"\u003Cwhy>\"` |\n| \"This fix is too big\" | `forge story new \u003CKEY> --from-fix \u003Cfix>` |\n| \"Let this fix go over the limit\" | `forge fix allow-large \"\u003Creason>\"` |\n| \"Build it\" | `forge work \u003Citem>` |\n| \"Tell the worker this round\" | `forge work \u003Citem> --note \"\u003Ctext>\"` |\n| \"Ask Codex about this code\" | `forge ask \"\u003Cquestion>\"` |\n| \"Close it\" or \"Is it ready?\" | `forge close \u003Citem>` |\n| \"Land it\" | `forge land \u003Citem>`, run in the background and watched like `forge work` |\n| \"Merge this ready item\" | `forge merge \u003Citem>` when the default branch allows agent merges |\n| \"Let the agent merge\" | The owner runs `forge merge enable` in their own terminal; never you |\n| \"What should we build?\" or \"Find the real problem\" | Discovery, below |\n| \"Is it worth building?\" | `forge spec payback --build-days \u003Cdays> --day-rate \u003Crate>` plus a value group |\n| \"Save this spec\" | `forge spec save \u003Cslug>` |\n| \"The spec is confirmed\" | `forge spec confirm \u003Cslug> --by \"\u003Cname>\"` |\n| \"Record the check-back result\" | In a fix: `forge spec measure \u003Cslug> --result \"\u003Cresult>\"` |\n| \"Record a decision\" | `forge decision new \u003Cslug>` |\n| \"The decision is accepted\" | `forge decision accept \u003Cslug> --by \"\u003Cname>\"` |\n| \"Add it to the roadmap\" | `forge roadmap add \u003Cspec>` |\n| \"The story is finished\" | `forge story done \u003CKEY> \"\u003Coutcome>\"` |\n| \"Is my setup healthy?\" or \"Fix my setup\" | `forge doctor`, then `forge doctor --fix` for what it can repair |\n| \"Set up a new repo\" | `forge init` |\n| \"Bring our live app into Forge\" | Adopt a live app, below |\n| \"Switch to Codex workers\" or \"Change the test command\" | Ask, then in a fix: edit `forge.toml` (never its `merge` setting), `forge close \u003Cfix>` |\n| \"Upgrade Forge\" | Upgrade Forge, below |\n\nThe human approves stories and chooses between options. In a client repo before the default\nbranch has an accepted sign-off, the agent runs `forge merge \u003Citem>` once `forge close` says Ready.\nAfter sign-off, the default branch's `forge.toml` merge setting applies: the human merges by\ndefault (`merge = \"human\"`), or the agent runs `forge merge \u003Citem>` for `merge = \"agent\"`.\nForge's own repo follows its setting throughout. Never run `gh pr merge`; the agent merges only\nthrough `forge merge`. Ask one question at a time: a decision gets options with your recommendation\nfirst, a question of fact gets neutral choices.\n\nGive each question one line of context and a header of 12 characters or less. Use 1-5 word options\nthat say what happens, with the recommended one first for decisions. Use no IDs, paths or slugs in\nquestions; write for the human's choice.\n\nThe human never edits `forge.toml`; you keep it. When a setting must change, ask first with\noptions, then make the change yourself in a fix: `forge fix start`, the edit, then `forge close`.\nThe `merge` setting is the owner's, because it is a gate on your own work: never change it to\n`\"agent\"` or run `forge merge enable`, even when the owner asks, and never merge a change to it.\nWhen agent merges are off and the owner wants you to merge, tell them to run `forge merge enable`\nin their own terminal; it opens the change for them to merge.\n\nGive status updates in one shape: `Ready to merge (n): ... · Needs you (n): ...`.\n\n## Handoff\n\n`.git\u002Fforge\u002Fhandoff.md` in the main checkout, shared by every worktree, carries your state across\na compaction. Before each compaction Forge rewrites its current-state part from `forge next` and\nkeeps everything under `## Decisions and lessons`. Add one line there at each milestone: a story\napproved, a task merged, a decision the owner made, a lesson learned or a mistake you won't\nrepeat. After a compaction or in a new session, read it first. The file is local and never\ncommitted.\n\n## Coaching\n\nThe first time each of these happens for a person, add one plain sentence saying what just\nhappened and what they can do next. Say it once, then never repeat it, and never name commands\nunless they ask. Note each one in the handoff so a new session doesn't repeat it.\n\n- 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.\"\n- 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.\"\n- A part starting: \"A worker is building this part on its own copy; you can keep planning meanwhile.\"\n- A pull request ready: \"This part passed its tests and review; you can look it over before it merges.\"\n- A merge: \"This part is now in the main code; you can try it there or pick what comes next.\"\n- A prototype demo: \"The customer has seen it working; you can tell me what they did and said to shape the next round.\"\n- Sign-off: \"The customer approved the prototype; you can now choose the first real story to plan.\"\n\n## New directions\n\nGrill any request with more than one reasonable reading or no stated done-when before starting a\nfix or story. Ask one question at a time with your recommendation and why; look up facts in the\nrepo instead of asking the human. A clear request with a stated done-when can go straight ahead.\n\nWhen the human states a new direction, principle or value, grill how it applies before changing\nanything. Ask one question at a time with your recommended answer and why; look up facts in the\nrepo instead of asking the human. Continue until the plan for applying it is agreed, then make\nthe changes.\n\n## Discovery\n\nEvery ask is a guess about a problem: find the problem before anything is planned. The worked\nexample, question bank, customer call script and outlines for the pre-meeting brief and recap are\nin [the reference page](fde.md).\n\n**By size.** On a fix or an everyday story, interview the engineer, and through them the\ncustomer: one question per turn, about something that already happened. Offer no solutions while\ndiscovering, and praise isn't evidence. A question of fact gets neutral choices; a decision gets\nyour recommendation first. Add a one-line `Why I ask:` to each question until the engineer says\nthey know why. Ask at most two questions for a fix and eight for a story, then write what is\nstill unanswered as `unknown`.\n\n**A new project.** On a new project, or an ask no confirmed spec covers, run this discovery\nwith the story limit. Before the first meeting, draft a one-page pre-meeting brief in\n`docs\u002Fcontext\u002F` from the prospect's website: their likely jobs, two or three guessed problem cards\neach marked `(guess)`, their terms, and the first five questions to ask. During discovery, keep\nthe customer's own words in `## Words they use` in `docs\u002Fproduct\u002FDISCOVERY.md`, one\n`- \u003Ctheir word>: \u003Cwhat it means>` line each. Ask for the spreadsheet or form they use today and\nkeep only its column headers, never its rows. The same day, draft a recap in `docs\u002Fcontext\u002F` for\nthe customer to confirm: their problem in their words, the cost in their numbers, the one task\nthe demo will cover, who signs off, the open \"ask the client\" questions and the demo date. When\nthey reply, record the Demo workflow and Sign-off person answers from it with `client` as the\nsource, as `- Demo workflow: \u003Ctask> (client, \u003CYYYY-MM-DD>)` and `- Sign-off person: \u003Cname, role>\n(client, \u003CYYYY-MM-DD>)`. The salesperson sends the recap; Forge sends nothing.\n\n**The card.** Write each problem as a card under `## Problems` in `docs\u002Fproduct\u002FDISCOVERY.md`,\nadding the section to an older file on first use: `### \u003Cshort problem title>`, then Job,\nWorkaround, Cost, Who feels it, How often and Evidence. Write customer notes in `docs\u002Fcontext\u002F`\ninto cards and leave the notes where they are. Name the chosen card's heading in the brief's\nSummary and the spec's Why. Costs use rounded rates, never real salaries.\n\n**Options.** For the chosen problem, offer two to four options, always with `Don't build` and\n`Smallest slice`, plus `Use what they have` (a setting, report or process change in tools they\nalready run) whenever one could do the job. Give each option that builds something its own\n`forge spec payback` line, and recommend the one with the fewest months among those answering\nbuild or smallest slice first; a tie goes to the smaller build. If none does, recommend don't\nbuild, or find out first when an option's value can't be estimated. The human chooses; write the\nchoice and one line of why into the spec's Behaviour.\n\n## Prototype\n\nIn a new client repo, follow the FDE route: start with discovery of the customer's job,\nworkaround, cost, people, frequency and evidence; build the smallest working prototype that tests\nthe riskiest part of that problem; demo it; review the whole prototype and answers; obtain the\ncustomer's named sign-off;\nthen create stories. Use prototype fixes before sign-off. The salesperson can be the FDE at first;\nthe developer takes over with `docs\u002Fproduct\u002FDISCOVERY.md`, `docs\u002Fproduct\u002FBRIEF.md` and the customer\ncall script. Push back when a requested feature does not serve the problem card: explain why and\noffer to note it for after sign-off. Keep the same app as it grows into production.\n\nAlways build the demo-data loader in the first version, so the customer sees their own kind of\nwork instead of empty screens (see demo-data.md). Use the customer's words\nfrom `## Words they use` in `docs\u002Fproduct\u002FDISCOVERY.md` for screen labels. Tell the salesperson\nthey can point at the screen: click an element in the demo build, write what's wrong and paste the\noutput to the agent.\n\nFor each demo round, gather all requests from one conversation into one prototype fix. Build,\ntest, review and merge that round before starting another. Tell the salesperson what changed in\nthe demo: \"the next version is live\" or \"the reviewer found a missing error message\". Do not\nuse Forge's words (fix, worktree, branch, pull request) in progress updates to the salesperson.\nWhen `forge next` says to connect the repo to our deploy platform, tell the salesperson to use\ntheir own login, pick a subdomain and record its address under `## Demo` in\n`docs\u002Fproduct\u002FBRIEF.md` as `- Address: \u003Curl>`. Copy that address into the sign-off decision.\n\n**The demo.** Every demo follows five steps, in order:\n\n1. their workaround today;\n2. the same job in the app;\n3. the time or money it saves, in their numbers;\n4. they take the controls;\n5. ask \"what would stop you using this?\"\n\nSend the demo link only after the guided demo, never before it. With each new version, draft a\nthree-line \"what changed\" note for the salesperson to send: what they can do now, what changed\nsince their last look, and what to try first, all in their words.\n\nAfter each demo, ask the salesperson one question at a time: what the customer did themselves,\nwhat they said word for word, and what they asked for. Write the answers under\n`## Prototype notes` in `docs\u002Fproduct\u002FDISCOVERY.md` as one `### \u003CYYYY-MM-DD>` block with `- Did:`,\n`- Said: \"\u003Ctheir words>\"` and one `- Asked:` line per request, ending each request in\n`(serves the problem)` or `(after sign-off)`.\n\nAsk one topic at a time when it first changes what you are building. Skip a topic the repo already\nanswers. In the options column, our default is first where there is one; questions of fact have\nno default. Offer **Ask the client** on every question and add it to the customer call script in\n`docs\u002Fproduct\u002FDISCOVERY.md`. For a topic that may wait, also offer **Decide later**. Standards\nalready decide logging, security and error handling; take those defaults and include them in the\nread-back without asking again. The first seven topics must have answers from the client,\nsalesperson or developer before sign-off; a default or agent-only answer does not settle them.\n\n| Topic | Question | Options (default first) | Before sign-off |\n|---|---|---|---|\n| Sign-off person | Who at the customer approves the prototype? | name and role | must |\n| Demo workflow | Which one task should the demo let them do from start to finish? | from the problem card | must |\n| Users and roles | Who uses it, and what can each kind of user do? | admin and staff; other | must |\n| Existing systems | Which systems must this work with? | none; CRM; accounting; email or SMS; payments; company sign-in | must |\n| Sign-in | How will people sign in? | email and password; company sign-in (Google or Microsoft) | must |\n| Personal data | Will it hold personal, health or payment data, or data that must stay in one country? | none; personal only; regulated | must |\n| Production host | Where will the real app run? | our platform; the client's cloud; the client's servers | must |\n| Data import | Does data need to come in from today's tools? | no; a spreadsheet; another system | may wait |\n| Email or SMS | Which provider sends messages? | none yet; the client's provider | may wait |\n| Domain | Which web address? | our subdomain; the client's domain | may wait |\n| Backups and uptime | How much downtime or data loss is acceptable? | the platform's daily backups; stricter | may wait |\n| Log retention | How long must logs be kept? | the platform's default; longer | may wait |\n\nKeep one `## Answers` section in `docs\u002Fproduct\u002FBRIEF.md`, one line per topic. Record an answer as\n`- \u003CTopic>: \u003Canswer> (\u003Csource>, \u003CYYYY-MM-DD>)`, with the client, salesperson, developer, our\ndefault or agent as its source. Record an open request as\n`- \u003CTopic>: ask the client (\u003Cwho asked>, \u003Cdate>)`; replace it with the sourced answer when the\nclient replies. Only a may-wait topic can read `- \u003CTopic>: later, when \u003Ctrigger>`.\n\n**Sign-off.** Before anyone asks for sign-off, hold one read-back call with the customer that\ngoes through every answer on the answers page: our defaults, the agent's guesses and the topics\nmarked later. Settle every open must-answer topic in that call: `forge next` lists those still\nmissing, malformed, or marked ask the client or later, and sign-off also refuses one answered by\nour default or the agent, so record each as the client, salesperson or developer answered it. Then\nrun the strict sign-off review before anyone asks for sign-off: write `forge decision new\nclient-signoff` (customer, demo address, and the answers page copied word for word, leaving\napproved via and approved on empty), and run `forge decision accept client-signoff --by \"\u003Cname>\"`\nbefore any reply is recorded; it runs the strict review alone and stops. That review always runs\non `gpt-6.1-sol` at high effort, whatever `forge.toml` says, and refuses a run on any other model\nor effort. Fix what it finds and run it again. Once it passes, tell the salesperson to ask the\ncustomer's named person for sign-off their own way. Draft no sign-off email; Forge sends nothing. When they bring the reply back, record\nit in `approved_via` and `approved_on`, then run `forge decision accept client-signoff --by\n\"\u003Cname>\"` again to accept. The customer's reply is the approval evidence the sign-off decision\nrecords.\n\nOn Codex, every other review runs on `[models.review]` in `forge.toml`, which `forge init` sets\nto `gpt-6.1-sol` at high effort; a prototype fix before sign-off gets a light review on\n`gpt-6.1-sol` at medium effort that blocks only on P0 findings.\n\nWhen a later story needs a topic marked later, its cold read reports `Decide first: \u003Ctopic>`.\nAsk that one question, put the answer in the finding's disposition and the story's Notes as\n`Decided: \u003Ctopic>: \u003Canswer> (\u003Csource>, \u003Cdate>)`, and make the first task update the answers page.\nUntil the decision, use a fake provider for an external service.\n\n## Adopt a live app\n\nAn app already in production joins Forge through one fix and one pull request the human merges.\nAdopting changes no app code.\n\n1. Write the codebase report in `docs\u002Fcontext\u002Fcodebase.md`: the stack and how to run it; the tests\n   and the areas they don't cover; the CI workflows and the checks branch protection requires; what\n   a merge triggers; branch rules and reviewers; the hook tools already in use; secret files and\n   variables by name only, never their values; where personal data lives; the migration tool; and\n   the danger zones.\n2. Mark as danger zones the most-changed, most-reverted and most-hotfixed files in git history. A\n   story that touches one names it under Risks.\n3. List the open pull requests and branches in the report, so a story's plan avoids colliding with\n   a teammate's work.\n4. Link or import the repo's existing decision records and design docs as Forge decisions:\n   `forge decision new \u003Cslug>`, the original linked or copied unchanged under the line\n   `Imported from \u003Cpath>.` Don't rewrite them.\n5. Read the review comments of about the last 100 merged pull requests. Each rule reviewers enforce\n   repeatedly becomes a House rule citing the pull requests it came from.\n6. Ask the human three questions, one at a time, with options: who approves stories, who merges,\n   and what must never be touched.\n7. Write the answers and the reviewers' rules under `## House rules` in AGENTS.md, outside Forge's\n   block. The repo's own rules win where they differ from Forge's default-stack conventions.\n   A rule every review must follow, such as which tests a kind of change needs, goes under\n   `## Review rules` in AGENTS.md, outside Forge's block: every review reads that section from the\n   default branch and follows it.\n\nOn a live app, every story and fix also follows these:\n\n- Before changing code no test covers, first add a test that pins today's behaviour.\n- Migrations only add, and work with the previous version of the app still running.\n- A change users would notice ships behind the team's own feature flags.\n- No production credentials on this machine; never ask for them.\n\n## Upgrade Forge\n\nAn upgrade is one fix. Its pull request carries the new version and every file Forge keeps in the\nrepo, rewritten by that version.\n\n1. Ask which release to move to, recommending the newest.\n2. `forge fix start \"Upgrade Forge to \u003Crelease>\" --done \"Forge runs \u003Crelease>\"`.\n3. In the fix's folder, set `version` in `forge.toml` to the release, such as `\"v1.2.0\"`.\n4. Install that release: `uv tool install git+https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge@\u003Crelease>`.\n5. Run `forge sync` in the fix's folder and commit everything it wrote.\n6. `forge close \u003Cfix>`. If it names files that aren't what `forge sync` writes, go back to step 5.\n\nUntil the upgrade merges, the default branch keeps working with the new release installed.\n\n## Planning a story\n\nUse one framing line before showing a story in Plan Mode:\n`Approving: \u003Ctitle>, \u003Cn> parts, \u003Crisks>`.\n\nThe owner approves only the top of the story doc. Show it from its title down to\n`## For the builders`, unchanged, in Plan Mode and exit Plan Mode with that part as the plan; in\nCodex, show the same part, then ask the approval question `forge next` gives. A doc with no\n`## For the builders` heading is shown whole. The approval binds \"What changes for you\" and\n\"Done when\", so tightening anything below `## For the builders` needs no new approval, while\nchanging a result or \"What changes for you\" does.\n\n- Done when: a few results the client or their user can observe, each tracing to the spec's\n  behaviour or success measure. Each item is one bold plain sentence and nothing more, with no\n  code names, file paths or test names. \"Code exists\" is not a result.\n- Each item's evidence, edge cases and the test or check that proves it go under the same number in\n  `### Done-when details`, the first section under `## For the builders`. Workers and reviewers\n  get the entries of the items their task covers. An item with nothing to add has no entry.\n- Done-when or Notes names supported inputs and exclusions. A dismissal that narrows those\n  inputs needs an amendment to the story doc before the review can close.\n- Put Risks right after Done when, then the `## For the builders` heading, so the owner's\n  sections come first and everything for the agents sits below.\n- Tasks: each row names the Done-when items it Covers, its Scope (the paths it may change) and\n  its Tests. A task that covers nothing is cut; work wanted later goes to the spec's Out of scope.\n- The Tests column names one end-to-end case per Done-when item that changes runtime behaviour,\n  and none for settings, docs, deletions or test-only items: the check the item names proves those.\n- Keep tasks small: at most three Done-when items and about 400 changed lines each.\n- Shared seams first: when two tasks share a function, field, file format or command, the first\n  task pins it. It commits the shared names and stubs plus one test that crosses both sides, and\n  the tasks that use it list it under After.\n- Aim for parallel work: split tasks so each owns its files. A line several tasks would edit (a\n  command-table row, a guide list or a registry) goes to one task, or to a small last wiring\n  task. Use After only when a task needs another task's code.\n- End the Tasks section with its one `New moving parts:` line (see Build simple).\n- Risks names every one-way step: deleting data, a destructive migration, a new vendor.\n- Use the stack already in the repo. Ask the human only when options differ in cost, lock-in or\n  reversibility. Replacing behaviour deletes the old path in the same story.\n\n**The roadmap.** Order stories by value, not by layer. The first story is the smallest slice, end\nto end and usable by the client; it brings only the setup, sign-in and data it needs. No\nsetup-only, platform or \"foundation\" stories. A story that no spec behaviour line needs is cut.\n\nStart every task and fix `forge next` lists as ready at once, and close each as its worker\nfinishes.\n\n## Cold read findings\n\n- `Unproven: item \u003Cn>: \u003Ccase>` or `Trap: \u003Ctrap>: item \u003Cn>`: add the case to that Done-when item\n  and its test to the Tests cell of the task that owns it. Never resolve one only in Notes.\n- `Disputed keep \u003Cn>: \u003Cwhy>`: the reader still disagrees with a finding you kept. Put it to the\n  human as one question with options, record the answer in the doc's Notes as\n  `Decided: \u003Cfinding>: \u003Canswer> (owner, \u003Cdate>)`, and give both the kept finding and the disputed\n  one the disposition `keep` citing that line.\n\n**Learn the traps.** After `forge story done` opens the outcome fix, look back at the story's\nreview rounds. For each kind of finding the plan missed that cost two or more fix rounds or hit\ntwo or more tasks, add one trap line to the `## Known traps` section of the repo's AGENTS.md,\noutside Forge's block, in the outcome fix's worktree; create the section when it is missing.\nCommit it before closing the fix. Every cold read checks plans against that section.\n\n## Steering a Codex worker\n\nWhen one sentence would help a worker finish its next round, give it with\n`forge work \u003Citem> --note \"\u003Ctext>\"`. The note appears under \"From the coordinator\" in that\nround's brief and is recorded with the turn. Give it again if a later round needs it; a note\ndoes not change the item's Scope. Read a close finding and the code it cites before deciding\nwhether the worker needs a note or the finding should be dismissed with evidence.\n\nIf a worker ends with a `Question:` paragraph, answer with\n`forge work \u003Citem> --note \"\u003Canswer>\"`. The worker waits for that answer: another work round\nwithout a note and `forge close \u003Citem>` both refuse until the answering round completes. The\nanswer returns to the same conversation when it can resume; a fresh brief carries both the\nquestion and answer. Workers change files outside Scope that the change needs and name them in\nthe handoff, so answer a Scope question only when the change isn't needed. If the answer needs a\nchoice the item does not settle, get that choice made before sending the note.\n\nFor a quick question about the code that needs no fix, run `forge ask \"\u003Cquestion>\"`. It asks\nCodex read-only in this checkout and prints the answer. Use `--model \u003Cmodel>` and\n`--effort \u003Ceffort>` to choose for this question; without them it uses the Codex entry of\n`[models.lite]` in `forge.toml`. Its records stay under `.git\u002Fforge\u002F`; the conversation is temporary and does not\nappear in the Codex chat list. If a tracked or untracked file changes during the turn, Forge\ndiscards the answer.\n\nEach kind in `forge.toml`'s `[models]` table may have a codex and a claude entry, such as\n`[models.build.codex]` and `[models.build.claude]`; a single entry counts only for its own model's\ntool (a gpt model is Codex's, any other Claude's). Workers use their `workers` tool's entry, the\nreview its engine's, and `forge ask` Codex's; a tool with no entry runs on its own settings.\n\nFor a side job inside your own session, hand it to one of Forge's subagent roles, which\n`forge sync` writes for both hosts from `forge.toml`'s models: `explorer` to read and trace code;\n`planner` and `architect` for planning and design choices; `debugger`, `security` and\n`performance` to diagnose; `worker`, `coder`, `frontend`, `tester` and `refactorer` to build.\nThe diagnosing and planning roles change no files. Building an item still goes through\n`forge work`. To change a role's model or effort, change `forge.toml` and run `forge sync`.\n\n## Build simple\n\nRead [standards.md](standards.md) beside this skill for Forge's principles, the client's app\nrules and the build-simple ladder. Apply its rules in every phase.\n\n**Finding forms.** `Simpler: \u003Ccut> → \u003Creplacement>` is P2, or P1 when a new moving part isn't\nnamed in the story. Untraced work: `Cut or defer: \u003Citem>`. An unmet Done-when item:\n`Not done: \u003Citem>` (P1). A missing rule-11 basic is its own P1, never `Simpler:`.\n\n## Closing\n\nBefore building a fix, check its brief for the five-code-file limit, interface globs and any\nrecorded allowance. If the work exceeds that boundary, promote it to a story or get the allowance\nrecorded before editing.\n\nMark generated files such as migration snapshots `linguist-generated` in `.gitattributes`, so\nreviews show them only as counts of changed lines.\n\nRead the worker's final handoff and resolve its stated blockers before `forge close`.\nWhen `forge close` stops on a finding, open the line it cites, and the code that line calls,\nbefore anything else. If the code proves the finding wrong, dismiss it with\n`forge close \u003Citem> --dismiss \u003Cn> --because \"\u003Cfile:line> \u003Cwhy>\"`; otherwise run\n`forge work \u003Citem>`. Reviewers are sometimes wrong, and every fix round costs another full review.\nWhen `forge land` stops on findings, after its three fix rounds or on a check it can't fix, judge\nthem the same way: dismiss with evidence, or `forge work \u003Citem>`, then `forge land \u003Citem>` again.\n\n## Check-back\n\nOnce every story from a spec is done and its check date has passed, `forge next` lists the check.\nMeasure it, record it in a fix with `forge spec measure \u003Cslug> --result \"\u003Cresult>\"`, then ask the\nhuman one question. Target met: \"Stop here\" (recommended) or \"Next problem card\". Target\nmissed: \"Change the slice\", \"Remove it\" or \"Find out why\". Adding features is never the default.\nAsk which parts the client doesn't use; each becomes a removal story on the roadmap.\n","\u003C!-- Generated by forge sync. -->\n\n# Forge\n\nStart with `forge next`. It says where things stand and gives the exact next command.\n\n| The human says | Run |\n|---|---|\n| \"What now?\" | `forge next` |\n| \"Show me progress\" | `forge board` |\n| \"Plan a new story\" | `forge story new \u003CKEY> \"\u003Ctitle>\"` |\n| \"Read the plan cold\" | `forge read \u003CKEY>`, or `forge read \u003Cslug>` for a spec |\n| \"I've amended it\" | `forge read \u003CKEY>` again, for the next round |\n| \"Start this task\" | `forge task start \u003CKEY>\u002F\u003CTASK>` |\n| \"Fix this small thing\" | `forge fix start \"\u003Cwhy>\" --done \"\u003Cdone when>\"` |\n| \"Name this fix\" | `forge fix start \"\u003Cwhy>\" --done \"\u003Cdone when>\" --slug \u003Cname>` |\n| \"Change this fix's Done-when\" | `forge fix amend \u003Cfix> --done \"\u003Cdone when>\" --because \"\u003Cwhy>\"` |\n| \"This fix is too big\" | `forge story new \u003CKEY> --from-fix \u003Cfix>` |\n| \"Let this fix go over the limit\" | `forge fix allow-large \"\u003Creason>\"` |\n| \"Build it\" | `forge work \u003Citem>` |\n| \"Tell the worker this round\" | `forge work \u003Citem> --note \"\u003Ctext>\"` |\n| \"Ask Codex about this code\" | `forge ask \"\u003Cquestion>\"` |\n| \"Close it\" or \"Is it ready?\" | `forge close \u003Citem>` |\n| \"Land it\" | `forge land \u003Citem>`, run in the background and watched like `forge work` |\n| \"Merge this ready item\" | `forge merge \u003Citem>` when the default branch allows agent merges |\n| \"Let the agent merge\" | The owner runs `forge merge enable` in their own terminal; never you |\n| \"What should we build?\" or \"Find the real problem\" | Discovery, below |\n| \"Is it worth building?\" | `forge spec payback --build-days \u003Cdays> --day-rate \u003Crate>` plus a value group |\n| \"Save this spec\" | `forge spec save \u003Cslug>` |\n| \"The spec is confirmed\" | `forge spec confirm \u003Cslug> --by \"\u003Cname>\"` |\n| \"Record the check-back result\" | In a fix: `forge spec measure \u003Cslug> --result \"\u003Cresult>\"` |\n| \"Record a decision\" | `forge decision new \u003Cslug>` |\n| \"The decision is accepted\" | `forge decision accept \u003Cslug> --by \"\u003Cname>\"` |\n| \"Add it to the roadmap\" | `forge roadmap add \u003Cspec>` |\n| \"The story is finished\" | `forge story done \u003CKEY> \"\u003Coutcome>\"` |\n| \"Is my setup healthy?\" or \"Fix my setup\" | `forge doctor`, then `forge doctor --fix` for what it can repair |\n| \"Set up a new repo\" | `forge init` |\n| \"Bring our live app into Forge\" | Adopt a live app, below |\n| \"Switch to Codex workers\" or \"Change the test command\" | Ask, then in a fix: edit `forge.toml` (never its `merge` setting), `forge close \u003Cfix>` |\n| \"Upgrade Forge\" | Upgrade Forge, below |\n\nThe human approves stories and chooses between options. In a client repo before the default\nbranch has an accepted sign-off, the agent runs `forge merge \u003Citem>` once `forge close` says Ready.\nAfter sign-off, the default branch's `forge.toml` merge setting applies: the human merges by\ndefault (`merge = \"human\"`), or the agent runs `forge merge \u003Citem>` for `merge = \"agent\"`.\nForge's own repo follows its setting throughout. Never run `gh pr merge`; the agent merges only\nthrough `forge merge`. Ask one question at a time: a decision gets options with your recommendation\nfirst, a question of fact gets neutral choices.\n\nGive each question one line of context and a header of 12 characters or less. Use 1-5 word options\nthat say what happens, with the recommended one first for decisions. Use no IDs, paths or slugs in\nquestions; write for the human's choice.\n\nThe human never edits `forge.toml`; you keep it. When a setting must change, ask first with\noptions, then make the change yourself in a fix: `forge fix start`, the edit, then `forge close`.\nThe `merge` setting is the owner's, because it is a gate on your own work: never change it to\n`\"agent\"` or run `forge merge enable`, even when the owner asks, and never merge a change to it.\nWhen agent merges are off and the owner wants you to merge, tell them to run `forge merge enable`\nin their own terminal; it opens the change for them to merge.\n\nGive status updates in one shape: `Ready to merge (n): ... · Needs you (n): ...`.\n\n## Handoff\n\n`.git\u002Fforge\u002Fhandoff.md` in the main checkout, shared by every worktree, carries your state across\na compaction. Before each compaction Forge rewrites its current-state part from `forge next` and\nkeeps everything under `## Decisions and lessons`. Add one line there at each milestone: a story\napproved, a task merged, a decision the owner made, a lesson learned or a mistake you won't\nrepeat. After a compaction or in a new session, read it first. The file is local and never\ncommitted.\n\n## Coaching\n\nThe first time each of these happens for a person, add one plain sentence saying what just\nhappened and what they can do next. Say it once, then never repeat it, and never name commands\nunless they ask. Note each one in the handoff so a new session doesn't repeat it.\n\n- 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.\"\n- 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.\"\n- A part starting: \"A worker is building this part on its own copy; you can keep planning meanwhile.\"\n- A pull request ready: \"This part passed its tests and review; you can look it over before it merges.\"\n- A merge: \"This part is now in the main code; you can try it there or pick what comes next.\"\n- A prototype demo: \"The customer has seen it working; you can tell me what they did and said to shape the next round.\"\n- Sign-off: \"The customer approved the prototype; you can now choose the first real story to plan.\"\n\n## New directions\n\nGrill any request with more than one reasonable reading or no stated done-when before starting a\nfix or story. Ask one question at a time with your recommendation and why; look up facts in the\nrepo instead of asking the human. A clear request with a stated done-when can go straight ahead.\n\nWhen the human states a new direction, principle or value, grill how it applies before changing\nanything. Ask one question at a time with your recommended answer and why; look up facts in the\nrepo instead of asking the human. Continue until the plan for applying it is agreed, then make\nthe changes.\n\n## Discovery\n\nEvery ask is a guess about a problem: find the problem before anything is planned. The worked\nexample, question bank, customer call script and outlines for the pre-meeting brief and recap are\nin [the reference page](fde.md).\n\n**By size.** On a fix or an everyday story, interview the engineer, and through them the\ncustomer: one question per turn, about something that already happened. Offer no solutions while\ndiscovering, and praise isn't evidence. A question of fact gets neutral choices; a decision gets\nyour recommendation first. Add a one-line `Why I ask:` to each question until the engineer says\nthey know why. Ask at most two questions for a fix and eight for a story, then write what is\nstill unanswered as `unknown`.\n\n**A new project.** On a new project, or an ask no confirmed spec covers, run this discovery\nwith the story limit. Before the first meeting, draft a one-page pre-meeting brief in\n`docs\u002Fcontext\u002F` from the prospect's website: their likely jobs, two or three guessed problem cards\neach marked `(guess)`, their terms, and the first five questions to ask. During discovery, keep\nthe customer's own words in `## Words they use` in `docs\u002Fproduct\u002FDISCOVERY.md`, one\n`- \u003Ctheir word>: \u003Cwhat it means>` line each. Ask for the spreadsheet or form they use today and\nkeep only its column headers, never its rows. The same day, draft a recap in `docs\u002Fcontext\u002F` for\nthe customer to confirm: their problem in their words, the cost in their numbers, the one task\nthe demo will cover, who signs off, the open \"ask the client\" questions and the demo date. When\nthey reply, record the Demo workflow and Sign-off person answers from it with `client` as the\nsource, as `- Demo workflow: \u003Ctask> (client, \u003CYYYY-MM-DD>)` and `- Sign-off person: \u003Cname, role>\n(client, \u003CYYYY-MM-DD>)`. The salesperson sends the recap; Forge sends nothing.\n\n**The card.** Write each problem as a card under `## Problems` in `docs\u002Fproduct\u002FDISCOVERY.md`,\nadding the section to an older file on first use: `### \u003Cshort problem title>`, then Job,\nWorkaround, Cost, Who feels it, How often and Evidence. Write customer notes in `docs\u002Fcontext\u002F`\ninto cards and leave the notes where they are. Name the chosen card's heading in the brief's\nSummary and the spec's Why. Costs use rounded rates, never real salaries.\n\n**Options.** For the chosen problem, offer two to four options, always with `Don't build` and\n`Smallest slice`, plus `Use what they have` (a setting, report or process change in tools they\nalready run) whenever one could do the job. Give each option that builds something its own\n`forge spec payback` line, and recommend the one with the fewest months among those answering\nbuild or smallest slice first; a tie goes to the smaller build. If none does, recommend don't\nbuild, or find out first when an option's value can't be estimated. The human chooses; write the\nchoice and one line of why into the spec's Behaviour.\n\n## Prototype\n\nIn a new client repo, follow the FDE route: start with discovery of the customer's job,\nworkaround, cost, people, frequency and evidence; build the smallest working prototype that tests\nthe riskiest part of that problem; demo it; review the whole prototype and answers; obtain the\ncustomer's named sign-off;\nthen create stories. Use prototype fixes before sign-off. The salesperson can be the FDE at first;\nthe developer takes over with `docs\u002Fproduct\u002FDISCOVERY.md`, `docs\u002Fproduct\u002FBRIEF.md` and the customer\ncall script. Push back when a requested feature does not serve the problem card: explain why and\noffer to note it for after sign-off. Keep the same app as it grows into production.\n\nAlways build the demo-data loader in the first version, so the customer sees their own kind of\nwork instead of empty screens (see demo-data.md). Use the customer's words\nfrom `## Words they use` in `docs\u002Fproduct\u002FDISCOVERY.md` for screen labels. Tell the salesperson\nthey can point at the screen: click an element in the demo build, write what's wrong and paste the\noutput to the agent.\n\nFor each demo round, gather all requests from one conversation into one prototype fix. Build,\ntest, review and merge that round before starting another. Tell the salesperson what changed in\nthe demo: \"the next version is live\" or \"the reviewer found a missing error message\". Do not\nuse Forge's words (fix, worktree, branch, pull request) in progress updates to the salesperson.\nWhen `forge next` says to connect the repo to our deploy platform, tell the salesperson to use\ntheir own login, pick a subdomain and record its address under `## Demo` in\n`docs\u002Fproduct\u002FBRIEF.md` as `- Address: \u003Curl>`. Copy that address into the sign-off decision.\n\n**The demo.** Every demo follows five steps, in order:\n\n1. their workaround today;\n2. the same job in the app;\n3. the time or money it saves, in their numbers;\n4. they take the controls;\n5. ask \"what would stop you using this?\"\n\nSend the demo link only after the guided demo, never before it. With each new version, draft a\nthree-line \"what changed\" note for the salesperson to send: what they can do now, what changed\nsince their last look, and what to try first, all in their words.\n\nAfter each demo, ask the salesperson one question at a time: what the customer did themselves,\nwhat they said word for word, and what they asked for. Write the answers under\n`## Prototype notes` in `docs\u002Fproduct\u002FDISCOVERY.md` as one `### \u003CYYYY-MM-DD>` block with `- Did:`,\n`- Said: \"\u003Ctheir words>\"` and one `- Asked:` line per request, ending each request in\n`(serves the problem)` or `(after sign-off)`.\n\nAsk one topic at a time when it first changes what you are building. Skip a topic the repo already\nanswers. In the options column, our default is first where there is one; questions of fact have\nno default. Offer **Ask the client** on every question and add it to the customer call script in\n`docs\u002Fproduct\u002FDISCOVERY.md`. For a topic that may wait, also offer **Decide later**. Standards\nalready decide logging, security and error handling; take those defaults and include them in the\nread-back without asking again. The first seven topics must have answers from the client,\nsalesperson or developer before sign-off; a default or agent-only answer does not settle them.\n\n| Topic | Question | Options (default first) | Before sign-off |\n|---|---|---|---|\n| Sign-off person | Who at the customer approves the prototype? | name and role | must |\n| Demo workflow | Which one task should the demo let them do from start to finish? | from the problem card | must |\n| Users and roles | Who uses it, and what can each kind of user do? | admin and staff; other | must |\n| Existing systems | Which systems must this work with? | none; CRM; accounting; email or SMS; payments; company sign-in | must |\n| Sign-in | How will people sign in? | email and password; company sign-in (Google or Microsoft) | must |\n| Personal data | Will it hold personal, health or payment data, or data that must stay in one country? | none; personal only; regulated | must |\n| Production host | Where will the real app run? | our platform; the client's cloud; the client's servers | must |\n| Data import | Does data need to come in from today's tools? | no; a spreadsheet; another system | may wait |\n| Email or SMS | Which provider sends messages? | none yet; the client's provider | may wait |\n| Domain | Which web address? | our subdomain; the client's domain | may wait |\n| Backups and uptime | How much downtime or data loss is acceptable? | the platform's daily backups; stricter | may wait |\n| Log retention | How long must logs be kept? | the platform's default; longer | may wait |\n\nKeep one `## Answers` section in `docs\u002Fproduct\u002FBRIEF.md`, one line per topic. Record an answer as\n`- \u003CTopic>: \u003Canswer> (\u003Csource>, \u003CYYYY-MM-DD>)`, with the client, salesperson, developer, our\ndefault or agent as its source. Record an open request as\n`- \u003CTopic>: ask the client (\u003Cwho asked>, \u003Cdate>)`; replace it with the sourced answer when the\nclient replies. Only a may-wait topic can read `- \u003CTopic>: later, when \u003Ctrigger>`.\n\n**Sign-off.** Before anyone asks for sign-off, hold one read-back call with the customer that\ngoes through every answer on the answers page: our defaults, the agent's guesses and the topics\nmarked later. Settle every open must-answer topic in that call: `forge next` lists those still\nmissing, malformed, or marked ask the client or later, and sign-off also refuses one answered by\nour default or the agent, so record each as the client, salesperson or developer answered it. Then\nrun the strict sign-off review before anyone asks for sign-off: write `forge decision new\nclient-signoff` (customer, demo address, and the answers page copied word for word, leaving\napproved via and approved on empty), and run `forge decision accept client-signoff --by \"\u003Cname>\"`\nbefore any reply is recorded; it runs the strict review alone and stops. That review always runs\non `gpt-6.1-sol` at high effort, whatever `forge.toml` says, and refuses a run on any other model\nor effort. Fix what it finds and run it again. Once it passes, tell the salesperson to ask the\ncustomer's named person for sign-off their own way. Draft no sign-off email; Forge sends nothing. When they bring the reply back, record\nit in `approved_via` and `approved_on`, then run `forge decision accept client-signoff --by\n\"\u003Cname>\"` again to accept. The customer's reply is the approval evidence the sign-off decision\nrecords.\n\nOn Codex, every other review runs on `[models.review]` in `forge.toml`, which `forge init` sets\nto `gpt-6.1-sol` at high effort; a prototype fix before sign-off gets a light review on\n`gpt-6.1-sol` at medium effort that blocks only on P0 findings.\n\nWhen a later story needs a topic marked later, its cold read reports `Decide first: \u003Ctopic>`.\nAsk that one question, put the answer in the finding's disposition and the story's Notes as\n`Decided: \u003Ctopic>: \u003Canswer> (\u003Csource>, \u003Cdate>)`, and make the first task update the answers page.\nUntil the decision, use a fake provider for an external service.\n\n## Adopt a live app\n\nAn app already in production joins Forge through one fix and one pull request the human merges.\nAdopting changes no app code.\n\n1. Write the codebase report in `docs\u002Fcontext\u002Fcodebase.md`: the stack and how to run it; the tests\n   and the areas they don't cover; the CI workflows and the checks branch protection requires; what\n   a merge triggers; branch rules and reviewers; the hook tools already in use; secret files and\n   variables by name only, never their values; where personal data lives; the migration tool; and\n   the danger zones.\n2. Mark as danger zones the most-changed, most-reverted and most-hotfixed files in git history. A\n   story that touches one names it under Risks.\n3. List the open pull requests and branches in the report, so a story's plan avoids colliding with\n   a teammate's work.\n4. Link or import the repo's existing decision records and design docs as Forge decisions:\n   `forge decision new \u003Cslug>`, the original linked or copied unchanged under the line\n   `Imported from \u003Cpath>.` Don't rewrite them.\n5. Read the review comments of about the last 100 merged pull requests. Each rule reviewers enforce\n   repeatedly becomes a House rule citing the pull requests it came from.\n6. Ask the human three questions, one at a time, with options: who approves stories, who merges,\n   and what must never be touched.\n7. Write the answers and the reviewers' rules under `## House rules` in AGENTS.md, outside Forge's\n   block. The repo's own rules win where they differ from Forge's default-stack conventions.\n   A rule every review must follow, such as which tests a kind of change needs, goes under\n   `## Review rules` in AGENTS.md, outside Forge's block: every review reads that section from the\n   default branch and follows it.\n\nOn a live app, every story and fix also follows these:\n\n- Before changing code no test covers, first add a test that pins today's behaviour.\n- Migrations only add, and work with the previous version of the app still running.\n- A change users would notice ships behind the team's own feature flags.\n- No production credentials on this machine; never ask for them.\n\n## Upgrade Forge\n\nAn upgrade is one fix. Its pull request carries the new version and every file Forge keeps in the\nrepo, rewritten by that version.\n\n1. Ask which release to move to, recommending the newest.\n2. `forge fix start \"Upgrade Forge to \u003Crelease>\" --done \"Forge runs \u003Crelease>\"`.\n3. In the fix's folder, set `version` in `forge.toml` to the release, such as `\"v1.2.0\"`.\n4. Install that release: `uv tool install git+https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge@\u003Crelease>`.\n5. Run `forge sync` in the fix's folder and commit everything it wrote.\n6. `forge close \u003Cfix>`. If it names files that aren't what `forge sync` writes, go back to step 5.\n\nUntil the upgrade merges, the default branch keeps working with the new release installed.\n\n## Planning a story\n\nUse one framing line before showing a story in Plan Mode:\n`Approving: \u003Ctitle>, \u003Cn> parts, \u003Crisks>`.\n\nThe owner approves only the top of the story doc. Show it from its title down to\n`## For the builders`, unchanged, in Plan Mode and exit Plan Mode with that part as the plan; in\nCodex, show the same part, then ask the approval question `forge next` gives. A doc with no\n`## For the builders` heading is shown whole. The approval binds \"What changes for you\" and\n\"Done when\", so tightening anything below `## For the builders` needs no new approval, while\nchanging a result or \"What changes for you\" does.\n\n- Done when: a few results the client or their user can observe, each tracing to the spec's\n  behaviour or success measure. Each item is one bold plain sentence and nothing more, with no\n  code names, file paths or test names. \"Code exists\" is not a result.\n- Each item's evidence, edge cases and the test or check that proves it go under the same number in\n  `### Done-when details`, the first section under `## For the builders`. Workers and reviewers\n  get the entries of the items their task covers. An item with nothing to add has no entry.\n- Done-when or Notes names supported inputs and exclusions. A dismissal that narrows those\n  inputs needs an amendment to the story doc before the review can close.\n- Put Risks right after Done when, then the `## For the builders` heading, so the owner's\n  sections come first and everything for the agents sits below.\n- Tasks: each row names the Done-when items it Covers, its Scope (the paths it may change) and\n  its Tests. A task that covers nothing is cut; work wanted later goes to the spec's Out of scope.\n- The Tests column names one end-to-end case per Done-when item that changes runtime behaviour,\n  and none for settings, docs, deletions or test-only items: the check the item names proves those.\n- Keep tasks small: at most three Done-when items and about 400 changed lines each.\n- Shared seams first: when two tasks share a function, field, file format or command, the first\n  task pins it. It commits the shared names and stubs plus one test that crosses both sides, and\n  the tasks that use it list it under After.\n- Aim for parallel work: split tasks so each owns its files. A line several tasks would edit (a\n  command-table row, a guide list or a registry) goes to one task, or to a small last wiring\n  task. Use After only when a task needs another task's code.\n- End the Tasks section with its one `New moving parts:` line (see Build simple).\n- Risks names every one-way step: deleting data, a destructive migration, a new vendor.\n- Use the stack already in the repo. Ask the human only when options differ in cost, lock-in or\n  reversibility. Replacing behaviour deletes the old path in the same story.\n\n**The roadmap.** Order stories by value, not by layer. The first story is the smallest slice, end\nto end and usable by the client; it brings only the setup, sign-in and data it needs. No\nsetup-only, platform or \"foundation\" stories. A story that no spec behaviour line needs is cut.\n\nStart every task and fix `forge next` lists as ready at once, and close each as its worker\nfinishes.\n\n## Cold read findings\n\n- `Unproven: item \u003Cn>: \u003Ccase>` or `Trap: \u003Ctrap>: item \u003Cn>`: add the case to that Done-when item\n  and its test to the Tests cell of the task that owns it. Never resolve one only in Notes.\n- `Disputed keep \u003Cn>: \u003Cwhy>`: the reader still disagrees with a finding you kept. Put it to the\n  human as one question with options, record the answer in the doc's Notes as\n  `Decided: \u003Cfinding>: \u003Canswer> (owner, \u003Cdate>)`, and give both the kept finding and the disputed\n  one the disposition `keep` citing that line.\n\n**Learn the traps.** After `forge story done` opens the outcome fix, look back at the story's\nreview rounds. For each kind of finding the plan missed that cost two or more fix rounds or hit\ntwo or more tasks, add one trap line to the `## Known traps` section of the repo's AGENTS.md,\noutside Forge's block, in the outcome fix's worktree; create the section when it is missing.\nCommit it before closing the fix. Every cold read checks plans against that section.\n\n## Steering a Codex worker\n\nWhen one sentence would help a worker finish its next round, give it with\n`forge work \u003Citem> --note \"\u003Ctext>\"`. The note appears under \"From the coordinator\" in that\nround's brief and is recorded with the turn. Give it again if a later round needs it; a note\ndoes not change the item's Scope. Read a close finding and the code it cites before deciding\nwhether the worker needs a note or the finding should be dismissed with evidence.\n\nIf a worker ends with a `Question:` paragraph, answer with\n`forge work \u003Citem> --note \"\u003Canswer>\"`. The worker waits for that answer: another work round\nwithout a note and `forge close \u003Citem>` both refuse until the answering round completes. The\nanswer returns to the same conversation when it can resume; a fresh brief carries both the\nquestion and answer. Workers change files outside Scope that the change needs and name them in\nthe handoff, so answer a Scope question only when the change isn't needed. If the answer needs a\nchoice the item does not settle, get that choice made before sending the note.\n\nFor a quick question about the code that needs no fix, run `forge ask \"\u003Cquestion>\"`. It asks\nCodex read-only in this checkout and prints the answer. Use `--model \u003Cmodel>` and\n`--effort \u003Ceffort>` to choose for this question; without them it uses the Codex entry of\n`[models.lite]` in `forge.toml`. Its records stay under `.git\u002Fforge\u002F`; the conversation is temporary and does not\nappear in the Codex chat list. If a tracked or untracked file changes during the turn, Forge\ndiscards the answer.\n\nEach kind in `forge.toml`'s `[models]` table may have a codex and a claude entry, such as\n`[models.build.codex]` and `[models.build.claude]`; a single entry counts only for its own model's\ntool (a gpt model is Codex's, any other Claude's). Workers use their `workers` tool's entry, the\nreview its engine's, and `forge ask` Codex's; a tool with no entry runs on its own settings.\n\nFor a side job inside your own session, hand it to one of Forge's subagent roles, which\n`forge sync` writes for both hosts from `forge.toml`'s models: `explorer` to read and trace code;\n`planner` and `architect` for planning and design choices; `debugger`, `security` and\n`performance` to diagnose; `worker`, `coder`, `frontend`, `tester` and `refactorer` to build.\nThe diagnosing and planning roles change no files. Building an item still goes through\n`forge work`. To change a role's model or effort, change `forge.toml` and run `forge sync`.\n\n## Build simple\n\nRead [standards.md](standards.md) beside this skill for Forge's principles, the client's app\nrules and the build-simple ladder. Apply its rules in every phase.\n\n**Finding forms.** `Simpler: \u003Ccut> → \u003Creplacement>` is P2, or P1 when a new moving part isn't\nnamed in the story. Untraced work: `Cut or defer: \u003Citem>`. An unmet Done-when item:\n`Not done: \u003Citem>` (P1). A missing rule-11 basic is its own P1, never `Simpler:`.\n\n## Closing\n\nBefore building a fix, check its brief for the five-code-file limit, interface globs and any\nrecorded allowance. If the work exceeds that boundary, promote it to a story or get the allowance\nrecorded before editing.\n\nMark generated files such as migration snapshots `linguist-generated` in `.gitattributes`, so\nreviews show them only as counts of changed lines.\n\nRead the worker's final handoff and resolve its stated blockers before `forge close`.\nWhen `forge close` stops on a finding, open the line it cites, and the code that line calls,\nbefore anything else. If the code proves the finding wrong, dismiss it with\n`forge close \u003Citem> --dismiss \u003Cn> --because \"\u003Cfile:line> \u003Cwhy>\"`; otherwise run\n`forge work \u003Citem>`. Reviewers are sometimes wrong, and every fix round costs another full review.\nWhen `forge land` stops on findings, after its three fix rounds or on a check it can't fix, judge\nthem the same way: dismiss with evidence, or `forge work \u003Citem>`, then `forge land \u003Citem>` again.\n\n## Check-back\n\nOnce every story from a spec is done and its check date has passed, `forge next` lists the check.\nMeasure it, record it in a fix with `forge spec measure \u003Cslug> --result \"\u003Cresult>\"`, then ask the\nhuman one question. Target met: \"Stop here\" (recommended) or \"Next problem card\". Target\nmissed: \"Change the slice\", \"Remove it\" or \"Find out why\". Adding features is never the default.\nAsk which parts the client doesn't use; each becomes a removal story on the roadmap.\n",{"name":5,"description":7},"main","7450721ddf8c0cbedf9d84c8311677a59f817675","tests\u002Ffixtures\u002Fforge-v1.2.2\u002Fsrc\u002Fforge\u002Ftemplates",9,"https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge","https:\u002F\u002Fgithub.com\u002Fknacklabs","https:\u002F\u002Fknacklabs.ai","2026-11-13 02:34:07",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add knacklabs\u002Fsymphony-forge --skill forge",{"tool":63,"command":64},"bunx","bunx skills add knacklabs\u002Fsymphony-forge --skill forge",{"tool":66,"command":67},"pnpm","pnpm dlx skills add knacklabs\u002Fsymphony-forge --skill forge","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002Fsrc\u002Fforge\u002Ftemplates\u002Fskill.md",true,[71],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"adapters\u002FAGENTS.md","REFERENCE","参考文档",2810,"https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002Fsrc\u002Fforge\u002Ftemplates\u002Fadapters\u002FAGENTS.md",[78,111,118,125,148,173],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":82,"sourceHtmlUrl":83,"categories":84,"keywords":90,"publishedAt":44},"01M6DYCB6Y89E5K32Y68B69PYS","simplified-technical-english","Writes and rewrites text in Simplified Technical English (ASD-STE100), a controlled language for clear technical documentation. Use when the user asks for STE, Simplified Technical English, controlled language, or plain technical writing, and when the user asks to write, rewrite, review, or check technical documentation, procedures, manuals, instructions, warnings, or reports.","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Fsrc\u002Fforge\u002Ftemplates\u002Fskills\u002Fsimplified-technical-english\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Fsrc\u002Fforge\u002Ftemplates\u002Fskills\u002Fsimplified-technical-english\u002FSKILL.md",[85],{"categoryNo":86,"categoryName":87,"taxonomyType":88,"taxonomyTypeDesc":89},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",[91,92,93,94,95,96,97,98,99,100,35,101,102,103,19,104,105,106,107,108,109,110,20],"technical","english","simplified technical english","writing","technical documentation","review","technical writing","documentation","ste","text","write","instructions","user","reports","issue","language","clear","rewrite","manuals","for",{"skillNo":112,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":113,"sourceHtmlUrl":114,"categories":115,"keywords":117,"publishedAt":44},"01M6DYB15X4C4A4025B0ZVCP6Q","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsimplified-technical-english\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fsimplified-technical-english\u002FSKILL.md",[116],{"categoryNo":86,"categoryName":87,"taxonomyType":88,"taxonomyTypeDesc":89},[91,92,93,94,95,96,97,98,99,100,35,101,102,103,19,104,105,106,107,108,109,110,20],{"skillNo":119,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":120,"sourceHtmlUrl":121,"categories":122,"keywords":124,"publishedAt":44},"01M6DYACDT517J69KRMM97BRG7","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsimplified-technical-english\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsimplified-technical-english\u002FSKILL.md",[123],{"categoryNo":86,"categoryName":87,"taxonomyType":88,"taxonomyTypeDesc":89},[91,92,93,94,95,96,97,98,99,100,35,101,102,103,19,104,105,106,107,108,109,110,20],{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":134,"publishedAt":44},"01M6DYD7G88G0Q478GTNAY7Y46","test-audit","Use whenever writing, changing, reviewing, or auditing tests. Gates new and changed tests and guides focused audits of low-value, implementation-coupled, or duplicative coverage and the test-only production seams it demands.","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002F.codex\u002Fskills\u002Ftest-audit\u002FSKILL.md",[131],{"categoryNo":132,"categoryName":133,"taxonomyType":88,"taxonomyTypeDesc":89},"01JBSEEDCAT000000000000008","测试与质量",[135,136,137,94,138,139,19,140,141,142,143,144,145,146,147],"test audit","test","audit","Production","coverage","only","implementation","gates","tests","guides","it","value","new",{"skillNo":149,"name":150,"nameZh":6,"description":151,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":152,"categories":153,"keywords":157,"publishedAt":44},"01M6DYD45AQMFJJ7C57078QY6K","app-baseline","The baseline every Forge client app gets without anyone asking. Use for any frontend or UI work in a Forge client repo, including screens, layout, navigation, forms, tables and prototype demos, before building or changing it.","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002F.codex\u002Fskills\u002Fapp-baseline\u002FSKILL.md",[154],{"categoryNo":155,"categoryName":156,"taxonomyType":88,"taxonomyTypeDesc":89},"01JBSEEDCAT000000000000009","前端开发",[158,159,160,161,162,163,5,164,165,166,19,167,168,169,170,171,145,172,110],"baseline","app","app baseline","frontend","prototype","ui","work","repo","before building","navigation","forms","layout","client","demos","tables",{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":179,"publishedAt":44},"01M6DYD06EG8TE3EXQA86XZHYV","remote-approval","Start a named Remote Control Claude Code session in a chosen checkout for an action the human must take from the Claude mobile app. Stories in every Forge repo can be approved from the one main chat; use this when another action needs its own session.","https:\u002F\u002Fgithub.com\u002Fknacklabs\u002Fsymphony-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fforge-v1.2.2\u002F.claude\u002Fskills\u002Fremote-approval\u002FSKILL.md",[],[180,181,182,183,39,5,165,184,19,185,186,187,49,188,25,189,159,190,191,110,192,20],"approval","remote approval","remote","code","session","mobile app","take","mobile","chat","control","checkout","can","stories"]