For a full-stack project, selecta tech stack combination that runs, is mutually compatible, and that the user can understand, and explain the terminology clearly along the way.
Boundaries
Do: stack selection, candidate comparison, combination compatibility determination, version compatibility verification, terminology explanation, and evaluating "continue / downgrade / switch stacks" during development due to requirement changes.
Don't do: requirement clarification and requirement interrogation alignment, architecture design, writing code, code review. Leave these to the corresponding skills.
Criterion: if the answer to something does not depend on "which set of technologies to choose", it does not belong to this skill.
When to use
- The user says "I want to build an X system, what tech stack should I use", "Drizzle or Prisma, which one", "can this combination run"
- The user does not understand full-stack terminology, or is using a meaning different from the engineering side ("interface", "frontend/backend", "deployment", "migration")
- Requirements have changed in a project with an existing stack, and the stack may need to change or features may need to be cut
- Need to check which version of a library should currently be used, or whether a certain version combination is compatible
Three iron rules
- All version numbers must be checked and verified on the spot. This skill contains no version numbers. For how to check, see
references/version-verification.md. For every selection, write the command and output intodocs/stack/version-evidence.md。 - Distinguish "technical hard constraints" from "ecosystem conventions". Only incompatibility confirmed by official documentation is a hard constraint; common pairings from scaffolds or the community are not. Confusing the two will make the user pay a downgrade cost for a feature that could have been kept. For the determination criteria, see
references/constraints-typescript.mdand the layered explanation inreferences/constraints-python.md. - Give ranked candidate combinations and let the user choose. Do not make the decision for the user, and do not give only one default stack. Give the reasons and costs for each candidate combination.
Process
Stage 1 · Lock down selection premises
Only askhard facts that would change the selection, and do not sort out requirements. Each question directly affects the candidate set at a certain layer.
Required questions (ask if any is missing):
- Deployment target and runtime environment (own servers / cloud hosting / edge / Serverless)
- Data scale, concurrency, data sensitivity (whether personal information is involved, whether auditing is needed)
- Existing team skills (determines onboarding cost, and is often the decisive factor)
- External services that must be integrated (payment, IM, maps, third-party APIs — these often directly determine the SDK and runtime)
Add as needed: budget and timeline, whether desktop/mobile is needed, whether multi-tenancy is needed, whether offline is needed.
Use the ask tool to ask all at once, and give a "no preference / don't care" exit for each question.
Completion criterion: obtain enough hard facts to narrow the candidate set to 2–3 stacks. If it still cannot be narrowed, clearly state which fact is missing and what disagreement its absence would cause, then proceed under the most conservative assumptions and mark those assumptions.
Stage 2 · Give candidate combinations + explain terminology
Read references/constraints-typescript.md or references/constraints-python.md(choose the track according to the user's language), and use the layer candidates and constraint table in it to generate 2–3 sets ofcompletecandidate combinations — each set covers all layers, leaving no gaps.
Each combination must provide:
- Selection for each layer(down to the specific library, not "some ORM")
- Rationale: why it matches the premises of phase one
- Cost: this set's weaknesses, what is given up, and its future ceiling
- Ranking basis: which premise determined that it ranks first
Term explanations(when a term appears for the first time, use the four-part format, taken from references/glossary.md):
- Technical term
- One sentence in plain language
- Why it affects you — tied to the specific consequences for the current project, not a generic definition
- Common misuse
Example (ORM):
ORM — an intermediate layer that lets you write TypeScript/Python instead of hand-writing SQL. Why it affects you: after the table structure changes, whether migration scripts can be generated automatically and whether they can be rolled back depends on it. Common misuse: thinking that using an ORM means you don't need to understand SQL. Index and transaction problems still have to be diagnosed with SQL knowledge.
Do not dump all the terms at once — only explain the terms that affect the user's current decision.
Completion criteria: the user receives 2–3 comparable complete combinations, and can restate each set's trade-offs in their own words.
Phase three · Produce the decision table and write it to disk
After the user makes a selection:
- Follow the format of
references/artifacts.mdto writedocs/stack/decision.md(decision table),docs/stack/version-evidence.md(version verification record). - In the consumer project's
AGENTS.md, append a stack section pointing todocs/stack/decision.md. First check whether that section already exists, to avoid adding it twice. - Tell the user: where the decision table is, and when it should be reviewed (recommended at each major version or requirement change).
Do version verificationbeforewriting the decision table: once the candidate combination is settled, run the verification commands layer by layer, and write the commands, output, and date into version-evidence.md. For layers where no official compatibility statement can be found, mark "no official statement found"; don't pretend to be certain.
Completion criteria: the three files have been written into the consumer project,AGENTS.md already points to the decision table, and the user knows what the next step is.
Review during development
Start when a requirement change may collide with the selection premises:
- Read
docs/stack/decision.md, and identify the layers that are affected. - Give three options, each stating its cost:
- Continue: leave this layer unchanged, and what the cost is
- Downgrade: keep the architecture but cut some functionality; what is cut and what the user will lose
- Switch stacks: replace this layer; the migration effort and what will be rewritten
- After the user makes a selection, append the conclusion to
docs/stack/change-impact.md(start a new one; do not overwrite history).
The review only assesses the impact on the selection; do not modify business code.
Completion criteria: the costs of the three options have been laid out, and the user has made a selection that is recorded on file.
Reference files
| File | When to read |
|---|---|
references/constraints-typescript.md |
TS track selection: layer candidates, hard technical constraints, ecosystem conventions |
references/constraints-python.md |
Python track selection: same as above |
references/version-verification.md |
Checking version numbers and compatibility: the npm / PyPI field sets and decision rules |
references/glossary.md |
Explaining terms: the four-part entry format |
references/artifacts.md |
Writing artifacts: formats for decision tables, version evidence, and change impact assessments |
references/templates/ |
Artifact templates ready to copy |
Common mistakes
- Giving version numbers from memory → must look them up now; this skill has no version table
- Presenting scaffolding preferences as hard constraints → especially easy to do with
vibestart-type matrices; this skill's two-layer classification exists for this reason - Leaving layers blank in a candidate combination (“use whatever database is suitable”) → every layer must be concrete
- Term dumping → explain only the terms that affect the current decision
- Repeatedly explaining things the user already understands → the criterion is “does this term affect his decision this time”