Stack Guides
Per-framework guidance the handoff_get_stack_guide tool returns to an agent.
An agent generating UI code needs to know more than tokens and component data, it needs to
know how this specific project is built: template language, CSS approach, and property
conventions. handoff_get_stack_guide returns exactly that as markdown.
Built-in profiles
Four stack profiles ship with handoff-app:
| Profile | Templates | CSS |
|---|---|---|
bootstrap-handlebars (default) | Handlebars (.hbs), class not className | Bootstrap 5 utilities + SCSS with var(--color-*) tokens |
react-tailwind | React TSX with typed props | Tailwind utility classes; tokens bound via CSS variables or tailwind.config |
react-scss | React TSX with colocated .scss modules or BEM-style classes | SCSS + design tokens as CSS variables; avoids Bootstrap unless the project explicitly mixes stacks |
tailwind-handlebars | Handlebars component structure | Tailwind utilities |
Resolution order
loadStackGuideMarkdown() checks, in order, the first that resolves:
HANDOFF_STACK_GUIDE_PATH: an explicit env var override (absolute path, or relative toHANDOFF_WORKING_PATH). Lets a project fully replace the guide with its own.{HANDOFF_WORKING_PATH}/docs/stack-guide.md: a per-project custom guide, no env var needed.- Built-in profile file: the matching
<profile>.mdfromhandoff-app's own stack-guides directory.
Which profile gets used
handoff_get_stack_guide (and handoff_get_project_context) resolve the active profile as:
an explicit stackProfile argument from the caller, else the HANDOFF_DEFAULT_STACK_PROFILE
env var, else bootstrap-handlebars.
Adding a new stack guide
A new profile needs: an entry in STACK_PROFILES (project-profile.ts), a matching
<profile>.md file in the stack-guides directory, and (if it changes translation defaults) an
update to the translationRules branch in buildProjectContext().
Relationship to the other Context tools
Stack guides are one of four Context tools that orient an agent before it writes anything:
handoff_get_project_context: which stack profile, project name, and Figma key are active right now.handoff_get_stack_guide: the authoring rules for that stack (this page).handoff_get_design_guidelines/handoff_get_brand_voice: workspace-authored Design.MD and brand-voice content, unrelated to the stack, these describe what the design system should look and sound like, not how to write the code.
See the Tool catalog for the full Context category.