fstack, the simple stack

fstack is a small collection of agent skills. Thirteen of them, exactly. Each one has a plain name and one job.

You invoke them as slash commands in Cursor, Claude Code, Codex, or any coding agent that reads markdown skills. /fstack-roast stress-tests a product idea. /fstack-interview records the business context. /fstack-nail clarifies a task. /fstack-plan writes a short plan. /fstack-build implements it one step at a time. /fstack-check reviews the result. /fstack-push commits it and pushes.

The whole thing installs with one command:

                                npx skills@latest add flaviocopes/fstack
                              

No dependencies, no build step, no config. Markdown files in folders. You can read every skill in a few minutes, and that is intentional.

The signature idea: one skill, /fstack-simplify, exists only to remove things. Every other stack reviews for bugs, security, and scope. fstack is the only one with a skill whose entire job is asking: can this be less?

fstack is free and MIT licensed. The source lives on GitHub.

Skill collections keep growing. Thirty skills, personas, pipelines, voice triggers. You install one, feel productive for a day, then realize you only remember four commands. You cannot hold the rest in your head, so you stop using it.

There is a second problem. Most stacks push toward long autonomous runs: the agent plans, builds, reviews, and ships while you watch. Then you get a mountain of output to review at the end, when your context is coldest and the cost of a wrong turn is highest.

And the complexity does not stay in the workflow. A process built to sound smart — phases, personas, ceremony — produces code that sounds smart too: layers, abstractions, and options nobody asked for. Overengineering in, overengineering out.

fstack bets the other way. The agent works in small steps. You approve; it executes. Decisions surface when they happen, not in a summary afterwards. A simple process, because simple processes produce simple software.

It distills four excellent skill collections — gstack, pstack, Compound Engineering, and Matt Pocock’s skills — through one filter: simplicity. That filter is not decoration. It is the product.

One command:

                                npx skills@latest add flaviocopes/fstack
                              

This copies thirteen folders of markdown into your agent’s skills directory. Nothing runs in the background. Nothing touches your PATH. There is no setup script because there is nothing to set up.

It works with Cursor, Claude Code, Codex, and any agent that supports the SKILL.md format. The skills are agent-agnostic on purpose: they say “run the tests”, never “use this specific tool”.

Want to check what you are installing first? Read the files on GitHub. All thirteen skills together are about 700 lines of markdown.

The five main skills form a loop you run for each piece of work:

                                fstack-nail → fstack-plan → fstack-build → fstack-check → fstack-push
                              

• /fstack-nail — make sure the agent understands the task before any work starts.
• /fstack-plan — write a short plan you approve before building.
• /fstack-build — implement the plan one small step at a time.
• /fstack-check — review the finished work with three questions.
• /fstack-push — commit any uncommitted work and push to the remote.

Two skills run before the loop. /fstack-roast, for when you have a product idea and want honest pushback before writing any code. And /fstack-interview, which asks about the business behind the project — demand, customer, pricing, risks — and records the answers in AGENTS.md so every future session starts informed.

Three skills you sprinkle in anywhere: /fstack-simplify when something feels bloated, /fstack-learn when something is worth remembering, and /fstack-counselors when a decision is big enough to want three independent model opinions.

And when you do not know where to start, /fstack is the front door. Describe what you want in plain words and it picks the right skill.

You do not have to run the full loop every time. A small fix might only need /fstack-build and /fstack-check. A messy file might only need /fstack-simplify. The loop is there when the work is big enough to deserve it.

Here is a full cycle on a real task: adding dark mode to a site. This is what working with fstack actually looks like.

You start at the front door:

The agent reads the relevant parts of the codebase, then asks its questions. All of them at once, five at most:

You confirm. The agent stops — /fstack-nail never starts planning on its own. You invoke /fstack-plan and it writes a plan file:

                                # PLAN.md

## What we're doing

Add a dark mode toggle to the site header. The preference
persists in localStorage and applies on every page without
a flash of the wrong theme on load.

## Steps

1. Add a blocking inline script that reads the stored theme
   and sets a class on <html> before first paint.
2. Add the toggle button to the header.
3. Wire the toggle to switch the class and save the choice.
4. Add dark values for the existing CSS custom properties.

## What we're NOT doing

- No theme customization beyond light/dark
- No per-page theme overrides
- No settings page — just the header toggle

## How we'll know it works

- Toggle the switch, refresh, theme persists.
- Hard-reload on a dark-mode profile: no light flash.
                              

Notice the “What we’re NOT doing” section. It is mandatory and can never be empty. Naming the tempting extras is how they stay out of the diff.

You approve the plan and say build. The agent takes one step at a time, and pauses when a step involves a real choice:

When all steps are done, /fstack-check reviews the work. Three questions, with evidence, and a one-line verdict:

That simplicity flag is worth a detour. You run /fstack-simplify, it proposes deletions, you approve two of them. Then /fstack-push commits the work and pushes it — no tests to re-run (check already proved it works), no ceremony.

One last thing. The theme-flash fix was non-obvious, so you run /fstack-learn:

                                ## 2026-07-11 — Theme flash on load
The theme must be set in a blocking inline script, not in React.
Anything set after hydration flashes the wrong theme.
                              

Three lines in LEARNED.md. The next session starts smarter.

The router. You describe what you want in plain words; it picks the right skill and starts it. Use it when you do not know, or do not care, which skill fits.

Type /fstack on its own, with no task, and it does not guess — it lists all twelve skills with a one-line description each and asks what you want to do. It is the menu when you forget what is available.

When you do give it a task, the routing map is simple:

• Product idea, not sure it’s worth building → /fstack-roast
• New project, the agent lacks business context → /fstack-interview
• Vague or new idea for this project → /fstack-nail
• Idea is clear, no plan exists → /fstack-plan
• Plan exists and is approved → /fstack-build
• Feels bloated or sloppy — one file or the whole codebase → /fstack-simplify
• UI looks off or inconsistent with the rest → /fstack-design
• Big decision, one opinion is not enough → /fstack-counselors
• Work is done, needs review → /fstack-check
• Project needs docs, or the docs have gone stale → /fstack-document
• Something worth remembering just happened → /fstack-learn
• Just want it committed and pushed → /fstack-push

It says which skill it picked and why, in one sentence. Then it runs that one skill and stops. It never chains skills into a pipeline.

If the request is truly ambiguous, it asks one clarifying question — one, not a questionnaire. Still ambiguous after that? It routes to /fstack-nail. That is what /fstack-nail is for.

The most expensive mistake in software is not a bug. It is spending three months building something nobody needs. /fstack-roast exists to catch that before any code gets written.

You bring a product idea. The skill asks up to five hard questions, picked for that specific idea:

• Who is the one person who needs this most? Describe them, specifically.
• What do they do today to solve this, even badly? What does that cost them?
• What is the strongest evidence someone wants this? Someone who would be upset if it vanished, not someone who said “cool”.
• What is the smallest version someone would pay for this week?
• How will the first 100 people find it?

You never face a blank page. Every question comes with 3 to 5 plausible answers drawn from your idea, plus the option to type your own — and the uncomfortable answer (“nobody has asked for this yet”) is always as easy to pick as the flattering ones. Then it stops and waits. A vague answer gets one follow-up push, not an interrogation.

The roast itself comes in three parts. What is real: the parts backed by evidence or a lived problem. What is wishful: the parts held up by hope, said plainly. The wedge: the smallest version worth building — shippable in days, not months. It ends with one verdict line: build the wedge, shrink it, or don’t build it.

Behind the questions sits a short list of principles about how small software products actually get built. The status quo is the real competitor — if people solve the problem with “nothing”, the pain is probably not real. Small and shipped beats big and planned. Charge real money, simply. Build for one specific person, and it is fine if that person is you. A demo is not a product. Distribution is part of the product. Boring tech ships.

What it must not do: flatter, kill ideas for sport, invent numbers or fake research, or start planning. Every roast ends with the best small version of the idea, even when the verdict is harsh. And the skill ends at the verdict — building is a separate decision, made by you.

Agents make product decisions all day — what to name things, what to simplify, what edge case matters. Without context, they guess. /fstack-interview fixes that once: it asks you about the business behind the project, then records the answers in AGENTS.md (or CLAUDE.md), so every future session starts informed.

It starts by reading the project — README, existing context files, the code — and never asks something the project already answers. Then it interviews you in rounds of 3 to 5 questions, not a wall of twenty. The questions are written for your specific project, never copied from a fixed questionnaire, and every question comes with 3 to 5 plausible answers to pick from, plus the option to type your own. It draws from areas like:

• Demand — Is there enough customer demand? Are people already searching for this, and where? How easy is it to get someone to sign up?
• Customer — Who exactly is this for? Who pays, and is that the same person who uses it?
• Business model — Can price times realistic volume produce revenue worth the effort? One-time or recurring, and why?
• Founder fit — Is this an industry you want to be in for years? What is your unfair advantage here?
• Status quo — What do people use today instead? What would make them switch?
• Distribution — How will the first 100 people find it?
• Risks — Which single assumption, if wrong, ends the project?
• Success — What does “working” look like in six months? What number would tell you to stop?

“I don’t know” is always one of the options. It is a valid answer — it gets recorded as an open question, not pushed past twice.

The output is a short Product context section — one line per answer — that the skill shows you before writing anything:

                                ## Product context

- **Product:** one line on what this is.
- **Customer:** who it is for, specifically.
- **Demand:** the evidence, in one line.
- **Business model:** pricing and why it can work.
- **Status quo:** what it replaces.
- **Distribution:** how people find it.
- **Not doing:** what is deliberately out of scope.
- **Open questions:** everything answered “I don’t know”.
                              

It never deletes what is already in the file, and it never judges the idea — that is /fstack-roast’s job. Roast decides whether to build. Interview makes sure the agent knows what it is building.

The most common failure in agent work is not bad code. It is good code for the wrong task. /fstack-nail exists to catch that before any work starts.

How it behaves:

1. Reads your request and the relevant parts of the codebase.
2. Asks at most 5 questions, all in one message. Only what it genuinely cannot infer.
3. Waits for your answers. No planning or coding in the meantime.
4. Replies with a 3-line summary: what we’re building, the one constraint that matters most, and what success looks like.
5. Asks you to confirm the summary. It does nothing else until you do.

The question cap has a second use: it is a task-size detector. If the agent has 8 genuine questions, the task is too big — and instead of asking them all, it says so and suggests splitting the work.

What it refuses to do: ask questions whose answers are already in the codebase or the conversation, and start planning or coding. The skill ends at the confirmed summary.

Turns a confirmed understanding into a plan you approve before building. The plan is a file — PLAN.md in the project root — not a message that scrolls away. Long-lived state belongs in the repo, not in chat memory.

The plan has exactly four sections. No others are allowed:

• What we’re doing — 2–4 sentences, plain language.
• Steps — a numbered list, max 7. Each step small enough to finish and verify in one sitting.
• What we’re NOT doing — mandatory, never empty. The tempting extras that are out of scope.
• How we’ll know it works — 1–3 plain checks you can actually try.

The whole plan fits on one page. If it does not, the task needs splitting into multiple plans. If any step feels big, it gets split or cut — never nested into sub-steps.

The “NOT doing” section is the one people copy into other workflows. Scope creep does not announce itself; it slips in as “while we’re here”. Writing the exclusions down turns them into something you can point at.

The skill ends at approval. It never starts implementing.

Executes the approved plan one step at a time. The rhythm is always the same:

1. Take the first unfinished step from PLAN.md.
2. Implement it with the smallest change that works.
3. Verify it — run it, run the test, load the page, whatever fits.
4. Report in 2–3 sentences: what changed, how it was verified.
5. Mark the step done in PLAN.md.

Before moving to the next step, one check: does it involve a real choice? A library, an API shape, naming that leaks into the public surface. If yes, the agent stops and asks, with a recommendation and a reason. If no, it continues.

What it refuses to do:

• Work that is not in the plan. Discovered work gets added to PLAN.md and asked about first.
• Refactoring surrounding code “while you’re there”.
• Batching multiple steps into one big change.
• Skipping verification on any step.

This is the tracer-bullet style: a thin, verified, end-to-end change at every step. You always know exactly where the work stands, because PLAN.md says so.

The signature skill, and it works at any scope: a plan, a diff, a single file, or the whole codebase. Point it at something and it hunts for unnecessary complexity, then proposes deletions and reductions. Only those — it is not allowed to propose additions.

It looks for smells like these:

• Dead code — unused files, exports, functions, imports
• Abstractions with one caller, or layers that only pass data through
• Config options nobody asked for
• Dependencies that replace a few lines of code
• Error handling for situations that can’t happen
• Comments that restate the code, or “for the future” code the future never needed
• Copy-paste blocks that drifted instead of being shared
• Words in docs or comments a beginner wouldn’t know

Each proposal is one line: what to remove, and what you would lose. Usually: nothing. On a whole-codebase pass it ranks them and groups by area, safe high-value cuts first — then applies the approved ones one batch at a time, running the tests between batches. That is the old “deslop the whole thing” idea, folded in: same job, just a bigger target.

Nothing gets applied without your approval. And it never rewrites working code to a different style — simpler, not different.

Run it on code, but also on plans before you build them, and on docs before you publish them. The fstack README itself went through it.

Agents write design slop: unmotivated gradients, five font sizes, off-palette colors, spacing that never repeats twice. /fstack-design makes new or changed UI adhere to the styles the project already has, then cleans up the rest against plain design sense.

The rule it enforces is simple: match what exists first. Before it touches anything, it reads the stylesheets, tokens, theme, and a few well-made existing components to learn the real palette, type scale, spacing scale, radius, and shadows. New UI should look like it belongs, not like it was pasted in from another app.

Then it reviews the target against two things: the existing system (where does it invent colors, sizes, or components instead of reusing what is there?) and plain design sense (hierarchy, alignment, consistent spacing, restraint). It flags the slop tells and maps each one back to the token or pattern it should use instead.

What it must not do: invent new colors, fonts, spacing, or components when fitting ones already exist; redesign the product; add a UI framework to “fix” things; or apply anything without approval. It aligns and cleans up — it does not reimagine.

Reviews finished work before it ships. Exactly three questions, in order, each answered with evidence:

1. Does it work? Prove it by running it — tests, the dev server, the actual command. “It should work” is not an answer. The real output gets pasted in.
2. Does it match the plan? Diff the work against PLAN.md. Flag anything built that wasn’t planned, and anything planned that wasn’t built. Then check the blast radius: what else could this change affect — callers, styles, routes, configs — and is each one fine?
3. Is it simple? A quick pass with the /fstack-simplify smell list. If something smells, it says so and suggests running /fstack-simplify — it never runs it automatically.

It ends with one verdict line: “Ready to push” or “Not ready: [reason]”.

The important constraint: /fstack-check reports and stops. It never fixes what it finds. Review and repair are different jobs, and mixing them is how “small fixes” turn into unreviewed rewrites. You decide what happens next.

It also refuses to add review dimensions. No security theater, no style nits. Three questions only.

After a piece of work, capture the single most useful lesson so future sessions start smarter. One lesson, not several. Three lines, not an essay.

Entries go in LEARNED.md in the project root, in this exact format:

                                ## 2026-07-11 — Theme flash on load
The theme must be set in a blocking inline script, not in React.
Anything set after hydration flashes the wrong theme.
                              

The bar for an entry: would this save future-you real time? Routine facts do not qualify. “Added a component” is not a lesson. “The webhook fires twice on retries, so the handler must be idempotent” is.

The skill checks the file for duplicates first, appends, and shows you what it added. It is the one fstack skill with no approval gate — appending three lines to a log is cheap, and friction here means lessons never get captured.

This is the compound step: each cycle of work leaves the project a little easier to work on than before. Agents read LEARNED.md at the start of a session and skip the potholes you already hit.

The deliberately small one. It commits whatever is uncommitted and pushes straight to the remote. That is the whole job — no tests, no deploy, no ceremony.

1. Check the working tree. If there are uncommitted changes, stage them and commit with a plain one-line message. If everything is already committed, skip straight to the push.
2. Push the current branch to its remote.
3. Report what happened in one line: the commit, if any, and the push result.

Deliberately narrow: it does not run tests or write a summary. /fstack-check already proves the work runs, so push does not repeat it. One skill, one job — get the code committed and pushed to the branch you are on.

It still refuses the shortcuts that cause incidents: no force-pushes, no pushing to a different branch than the current one, no skipped hooks, no amending commits already on the remote, and it warns instead of committing anything that looks like a secret.

Some decisions are big enough that one model’s opinion is not enough. Architecture choices, tricky trade-offs, “should we do X or Y”. /fstack-counselors convenes a council: the same question goes to the three most capable models available in your environment, each answers independently, and the answers get resolved into one definitive recommendation.

The mechanics matter. The question becomes one self-contained brief — the question, the relevant files and constraints, the answer format — and every counselor gets exactly that brief, in parallel, read-only. No counselor sees another’s answer. Independence is the whole point: three models that can copy each other are one model with extra steps.

If you do not name an effort level in your prompt, the council runs at medium, balanced reasoning — good thinking without the full cost and latency. Ask for the highest level when the decision is worth it.

The result comes in two parts. The verdict: one definitive answer. When the counselors disagree, the synthesis picks a side and says why — “all approaches have merit” is not a verdict. The council: each counselor’s opinion summarized in 2 to 3 lines, model named, with every disagreement flagged and resolved. A 2–1 split is reported as 2–1, never smoothed over.

It degrades honestly. If your environment cannot mix models, it runs three independent sessions of the best one — independent runs still surface disagreement. If it cannot run independent agents at all, it says so and answers directly. It never fakes a council. And it never convenes one for trivial questions: three models on a variable name is waste.

The council only reads and opines; it never changes files. Acting on the verdict is a separate decision — yours.

This skill distills the council-of-advisors pattern from counselors by Aaron Francis, a CLI that fans one prompt out to Claude, Codex, Gemini, and other locally installed agents. The fstack version uses whatever your environment already has — and if his CLI is installed, it is a fine way to run the fan-out.

Writes documentation about the project into a docs/ folder, in three layers from plain to deep. Run it once to create the docs. Run it again and it updates them to match the code as it is now — it does not start over.

It reads the project first — structure, entry points, main modules, data model, config, how to run and test — then writes three files:

• docs/overview.md — ELI5. What the project is, what it does, who it is for, in words a non-expert understands. No jargon.
• docs/architecture.md — How it works. The main pieces, how they fit, how data flows, the decisions that shaped it.
• docs/reference.md — The details. Directories and key files, config and environment, how to run, test, and build.

On the second run it switches to update mode: it re-reads the code, changes only what the code changed, keeps human edits that still hold, adds anything new, and flags anything the docs mention that no longer exists. It documents what the code actually does — not what it should do — and never sprawls past those three files. If a section balloons, that is a hint the project itself may be too complex.

fstack keeps project state in two plain files, committed to the repo like everything else. Chat history is a terrible database. Files survive sessions, agents, and machines.

PLAN.md is the current piece of work. Written by /fstack-plan, updated by /fstack-build as steps complete, diffed against by /fstack-check. When the work ships, the next plan replaces it.

LEARNED.md is the project’s memory. Appended by /fstack-learn, three lines at a time. A healthy one after a few months looks like this:

                                ## 2026-05-02 — Paddle webhooks retry
The purchase webhook fires again on timeout. The handler
must be idempotent on the transaction id.

## 2026-06-14 — Astro static routes win
A static page file beats the [slug] dynamic route at the
same path. No config needed, but easy to forget it exists.

## 2026-07-11 — Theme flash on load
The theme must be set in a blocking inline script, not in React.
Anything set after hydration flashes the wrong theme.
                              

That is the whole state model. Two files, both readable in under a minute, both diffable in code review. No dashboards, no databases, no session storage.

Every fstack skill is written against these rules. They are also decent rules for anything you write — docs, plans, commit messages.

1. Short sentences. One idea per sentence.
2. Short paragraphs, then a blank line.
3. No jargon. If a plumber wouldn’t understand the word, find a simpler one.
4. No personas. Skills describe steps, not characters. No “you are a senior architect”.
5. One job per skill. A skill that does two things is two skills.
6. Prefer deletion. When something can be shorter, make it shorter.
7. Every skill fits in ~150 lines. Over the cap means the skill is doing too much.
8. The human drives. Skills pause at decision points and ask. No long autonomous pipelines.
9. Agent-agnostic. Plain markdown, no hardcoded tool names.
10. Plain-English tone. Like explaining to a friend. No hype.

The line cap deserves a note. It is not about saving tokens. It is a forcing function: a skill you can read in two minutes is a skill you actually understand, and a skill you understand is a skill you can trust with your codebase.

fstack did not appear from nothing. It distills four collections, keeping the ideas and dropping the machinery.

From gstack (Garry Tan): the full lifecycle idea — think, plan, build, review, ship — the scope-reduction instinct of “strip to essentials”, and office hours, which /fstack-roast distills into five questions and a verdict. Left behind: the 30+ skill count, the personas, deploy orchestration, canary monitoring, iOS tooling, voice triggers.

From pstack (Lauren Tan): design before code, blast-radius thinking — know what your change touches before you ship it — and the router pattern of one entry point that picks the right skill. Left behind: parallel candidate arenas, depth-first ceremony, anything requiring worktrees.

From Compound Engineering (Every): the plan file as an artifact, the compound step of capturing one lesson after each piece of work, and the human-approves-the-plan checkpoint. Left behind: long autonomous runs and multi-agent review panels. fstack keeps the question those reviewers ask, not the roleplay.

From Matt Pocock’s skills: grilling — asking clarifying questions before work starts — the two-axis review (does it work / is it right), and the small, composable skill shape. Left behind: the full grill-with-docs machinery and TDD as a mandatory gate.

From counselors (Aaron Francis): the council-of-advisors pattern — the same question to multiple models, independently, second opinions rather than split work. That became /fstack-counselors. Left behind: the CLI itself, the adapters, the output directories. The skill uses whatever agents your environment already has.

And the one thing none of the sources has: a skill whose only job is asking “can this be less?”. That is /fstack-simplify, and it is why fstack exists as its own thing rather than a fork.

Do I need all 13 skills?
No. The loop is there for work big enough to deserve it. Plenty of tasks only need /fstack-build and /fstack-check. /fstack-simplify is useful entirely on its own.

Which agents does it work with?
Cursor, Claude Code, Codex, and anything else that reads SKILL.md files. The skills never reference agent-specific tools, so they degrade gracefully across hosts.

How is this different from gstack or pstack?
Those are bigger and do more — browser QA, deploy pipelines, security audits, parallel candidates. fstack is deliberately the small one: 13 skills, no personas, no pipelines, and a bias toward deleting things. If you want a virtual engineering team, use gstack. If you want a calm loop you can hold in your head, use fstack.

Can I edit the skills?
Yes, and you should. They are markdown files in your skills folder. If a rule does not fit how you work, change it. MIT licensed.

Does it send data anywhere?
No. There is no telemetry, no server, no account. It is text files that your agent reads.

Why the hard caps — 5 questions, 7 steps, 150 lines?
Caps are how simplicity survives contact with real work. Without them, questions multiply, plans nest, and skills bloat. Each cap doubles as a signal: hitting it means the task is too big, not that the cap is too small.

What happens when the plan turns out to be wrong mid-build?
The agent adds the discovered work to PLAN.md and stops to ask. You decide: amend the plan, or finish the current scope and plan the rest separately. What never happens is silent scope drift.

fstack exists because of the stacks it distills: gstack by Garry Tan, pstack by Lauren Tan, Compound Engineering by Every, and Matt Pocock’s skills. Go look at all four — they are generous, thoughtful work.

fstack is MIT licensed. Source, issues, and contributions: github.com/flaviocopes/fstack.