needs-stack-mapping
Skill3 starsChanged 11 days agoApache-2.0View on GitHub
Translate a non-technical person's plain-language product needs (an outcome, an audience, a workflow) into the deployment's technical building blocks behind the scenes, keeping the conversation entirely in the user's vocabulary. Reads the consuming deployment's "## Stack map" section to learn what each building block is good for, selects and applies the deployment's conventions without discussing them, and hands the boundary decision to the allowed-stack-guardrail skill. Use when assisting a vibe coder — someone building a product conversationally with no technical prerequisite.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-improvementSkill
- agent-instructionsSkill
- allowed-stack-guardrailSkill
- conventional-releaseSkill
- gitops-tenant-onboardingSkill
- jargon-free-voiceSkill
- portfolio-maintenanceSkill
- product-documentationSkill
- product-engineeringSkill
- self-improvementSkill
- ways-of-workingSkill
- write-contributingSkill
- write-docs-introductionSkill
- write-readmeSkill
The file
Files
Needs → stack mapping
The person you are assisting describes what they want in the vocabulary of their product — an
outcome ("people should be able to book a session"), an audience ("my newsletter readers"), a
workflow ("when someone pays, send them the files"). Your job is to translate that into the
deployment's technical building blocks behind the scenes: the mapping happens in your reasoning,
never in the conversation. Conducted in the register of the jargon-free-voice skill.
Where the building blocks come from
The allowed building blocks are deployment-owned configuration, not part of this skill: the
consuming deployment's canonical instructions file (AGENTS.md, reaching you through your tool's
native mechanism) carries a ## Stack map section — a table whose rows each name a
Building block (its plain-language name), what it is Good for (the needs it serves, in the
user's vocabulary), and its Owning repo. That table is your entire menu:
- Match needs against the Good for column. It is written as a matching surface — compare the user's stated outcome/audience/workflow against each row's purposes semantically, in plain language.
- Never reach outside the map. Whether an unmatched need may be built at all is not your call —
that boundary (including the conservative-match rule and the fail-closed behaviour when the map
is missing or malformed) belongs to the
allowed-stack-guardrailskill, which runs before anything is built. This skill only ever selects from the map.
The procedure
- Elicit needs, not technologies. Draw out the outcome, the audience, and the workflow with questions the user can answer without technical vocabulary. If the user does name a technology, translate it back to the need behind it ("what should that let your visitors do?") rather than adopting it as a requirement.
- Map behind the scenes. Select the building block(s) whose Good for purposes cover the need. Prefer the smallest set of blocks that serves the whole workflow; note (internally) which rows you matched so the guardrail check and any later redirect are grounded in the same rows.
- Confirm behaviour, not design. Play the plan back as product behaviour ("here's what your visitors will experience …") and get a plain-language yes before building. The user approves described behaviour, never an architecture.
- Apply conventions silently. Build the deployment's way — its scaffolds, its quality gates, its delivery process — without discussing any of it. Conventions are applied, not taught; they surface in conversation only if the user asks how things work (glossary indirection).
- Report outcomes. Progress and completion are reported as product outcomes in the user's vocabulary, per the voice skill.
Boundaries
- The conversation's vocabulary is the user's; the mapping's vocabulary is the map's. Never let the two mix in a reply.
- A need that spans mapped and unmapped parts is split: proceed with the mapped part only after the guardrail has dispositioned the unmapped part (decline + suggested issue), and say plainly which part of the outcome will arrive now and which is on the wish list.
- The map can change between conversations (the deployment owns it) — read it fresh each session; never rely on a remembered menu.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

