A build playbook for shipping real websites with coding agents. Not tied to any one agent: it is a folder of markdown, so it runs on Claude Code, Cursor, Windsurf, Codex, Copilot, Gemini CLI, or a chat window with no skills support at all.
Foreman's own site, built by running Foreman. If the playbook cannot produce one good page, it is not worth installing.
Coding agents removed the cost of writing a site. They did not remove the cost of deciding what it should be. So the internet now has thousands of sites that were built in an afternoon and look like each other: the same cream background, the same serif hero, the same three cards, the same accent, no domain, no metadata, no 404.
Foreman is the missing half. It turns the agent you are already talking to into a foreman: it interviews you, forces the decisions you would have delegated, locks a visual system before any code exists, writes one high-quality build brief, then asks whether to build it there or hand it over, and walks you through verification, DNS, and indexing until the thing is actually live.
You do not read Foreman. Your agent does.
Foreman is one folder of markdown. Nothing compiles, nothing runs, so it installs anywhere an agent reads files.
Claude Code. Both lines, in this order.
/plugin marketplace add Turki-Sh/Foreman
/plugin install foreman@alshuaibi
/plugin is a terminal-only dialog. If your session answers "/plugin isn't available in this environment", run the same two steps as shell commands and restart the session.
claude plugin marketplace add Turki-Sh/Foreman
claude plugin install foreman@alshuaibi
Claude apps. Download foreman.skill and upload it as a skill.
Cursor, Windsurf, Codex, Copilot, Gemini CLI, Cline, or any other coding agent. Clone the repo and copy the skill folder where your agent looks for skills or rules.
git clone https://github.com/Turki-Sh/Foreman.git
cp -r Foreman/plugins/foreman/skills/foreman ~/.agents/skills/
Common destinations: ~/.agents/skills/, ~/.cursor/rules/, ~/.codex/skills/, or a .github/ folder in the project. See AGENTS.md for per-tool paths and for what to do if your agent has no skills directory at all.
Any assistant with no skills support, including the web chat you already have open. Paste SKILL.md into the conversation and say "run this on me." The steps work without the references; the references only deepen them.
help me build my portfolio
The agent should answer with two questions, not with code. That is the whole point.
| Without Foreman | With Foreman | |
|---|---|---|
| First move | Generates a page | Asks what the site is for and who reads it |
| Copy | Written by the model | Extracted from you, with numbers |
| Design | Whatever the model defaults to | Locked tokens you chose from three variants |
| Scope | Everything it can think of | Explicit non-goals, written before the build |
| Done | It renders on your laptop | 375px, keyboard, Lighthouse, incognito, real 404 |
| Live | "Deployed" | DNS, SSL, sitemap, Open Graph, submitted and indexed |
Session flow. Eight steps with gates, written for the agent, not for you. It does not advance until each gate is met, it stamps which step you are on in every message, and it writes no line of the site until the brief is frozen.
Thirteen references, loaded only when the step arrives: content interview, design direction, the palette workflow, composition and choreography, the reference library, vibe-coded tells, stack choice, the build brief, performance and accessibility, metadata and 404, bilingual and RTL, verify and ship, and a full worked example.
Six fillable assets: a brand harness with three variants, a head metadata block with Open Graph and JSON-LD, a custom 404, robots.txt, sitemap.xml, and llms.txt.
No executable code. Foreman ships no scripts, no hooks, no MCP servers, and no slash commands. It is markdown and fill-in-the-blank templates, so you can read every line of it before you trust it. The one <script> tag in the repo is a type="application/ld+json" structured data block inside assets/head-metadata.html: inert JSON meant for your site's <head>, not code that runs when you install this.
See it run before you install it. The worked example is a full session from the first question to a frozen brief, including the thing that went wrong afterwards.
- The agent's ceiling is your brief. Model choice is a rounding error next to the quality of the specification.
- Non-goals are the highest-leverage lines you will write. Agents over-build by default, and one line prevents it.
- Decisions are yours, typing is theirs. Delegate the implementation. Delegating the judgment is what produces the default look.
Contributions are open in some areas and closed in others. CONTRIBUTING.md says which.
The most useful thing you can send is a failure the playbook did not intercept: your build broke, and Foreman never asked the question that would have prevented it. Post it on the meta thread. The most useful pull request is an install path for an agent I cannot test.
Built by Turki Alshuaibi, AI engineer. Everything in it came from shipping, and from watching capable engineers get stuck in the same handful of places, which are the failure modes listed at the end of the skill.
MIT. Use it, fork it, teach with it, ship client work with it.
MIT does require attribution: the copyright notice travels with any copy or substantial portion. Beyond that legal minimum, if Foreman shaped a site you are proud of, a line in your README or a link in the post is the thing that actually helps. Credit costs you nothing and it is how a playbook finds the next person who needs it.