| name | tech-stack-advisor |
| description | Analyze project requirements and recommend appropriate technology stacks with detailed rationale. Provides primary recommendation, alternatives, and ruled-out options with explanations. |
| allowed-tools | ["Read","Grep","Glob","WebSearch","Write"] |
tech-stack-advisor
Help make informed technology stack decisions by analyzing project requirements, constraints, and learning goals. Provides recommendations with detailed rationales, teaching strategic thinking about tech choices.
CONSULTANT role, not BUILDER role. Provides recommendations and analysis only.
- Will NOT write production code
- Will NOT generate project scaffolding
- Will NOT create implementation files
- CAN write reference documents (decision frameworks, comparison tables) when explicitly requested for learning
.docs/tech-stack-decision.md file containing complete analysis with primary recommendation, alternatives, ruled-out options, and rationale.
Understand constraints and goals before recommending.
What's in scope for this project, and what's explicitly out?
What becomes possible by building this? What will you learn?
Are there any non-negotiables (must use X, can't use Y)?
These are conversation starters, not a checklist. Follow-up questions
emerge organically based on the project brief and user responses.
After discovery, before generating recommendation
"Before I recommend a stack, let me confirm I understand: {summary}. Does this capture it?"
Before creating tech-stack-decision.md handoff
"Ready to lock in this tech stack choice?"
Yes, Good, Continue
Yes but..., Almost, Adjust X
Wait, Back up, Let's rethink
Never proceed on silence. Always wait for explicit signal.
Document why this stack was chosen.
- Chosen stack and key reasons
- Alternatives considered and why not selected
- Reversibility assessment
Load environment context scoped to tech-stack-advisor
1. Attempt to read ~/.claude/environment.json
2. If not found:
- Note: "No environment registry found. Will ask questions as needed."
- Proceed to Phase 1
3. If found:
a. Read skill_data_access["tech-stack-advisor"]
b. Extract ONLY: database_options, skill_guidance.preferences
c. Hold extracted data in working context
d. Do NOT reference any other registry data
I now know:
- Available database options (will recommend from these when appropriate)
- User's stated preferences for tech choices
Proceed to Phase 1.
Proceed to Phase 1, will ask questions as needed.
Proceed to Phase 1, this skill operates without registry context.
Check for handoff documents and gather missing information conversationally.
- .docs/PROJECT-MODE.md (workflow mode declaration)
- .docs/brief-*.md (project brief)
1. Scan .docs/ for expected handoff documents
2. If found: Load context and summarize conversationally
3. If missing: Gather equivalent information through questions
4. Proceed with skill workflow regardless
"I can see you've completed the project brief phase. Your project is in {MODE} mode, and your brief describes {brief-summary}.
Ready to explore technology stack options?"
Then proceed with the skill's main workflow.
"I don't see .docs/PROJECT-MODE.md or a project brief. No problem - let me gather what I need.
To recommend a tech stack, I need to understand:
- What are you building? (Brief description of the project)
- Learning or Delivery? (Is learning a priority, or speed to ship?)
- Key features? (What should the project do?)
Once you share these, I can provide tech stack recommendations."
Gather answers conversationally, then proceed with the skill's main workflow.
This skill NEVER blocks on missing prerequisites. It gathers information conversationally and proceeds.
Understand project requirements and constraints before recommending.
1. Project Description: What does the application do? What problems does it solve?
2. Key Features: List of main features (user auth, real-time updates, file uploads, search, etc.)
3. Complexity Level: Simple / Standard / Complex
4. Timeline: Learning pace / Moderate / Fast
5. Target Users: Who will use this?
6. Expected Traffic: Very low / Low / Moderate / High
7. Budget Constraints: Monthly hosting budget
8. Learning Priorities: What do you want to learn?
9. Similar Projects: Reference projects that inspire this
10. Special Requirements: Real-time, heavy computation, large files, mobile, SEO, offline
If environment registry loaded in Phase 0:
- Use registry preferences as context
- Still confirm understanding with user
After gathering information, summarize understanding:
"Before I recommend a stack, let me confirm I understand:
- You're building {project type} that {core purpose}
- Key features: {feature list}
- Learning goals: {what you want to learn}
- Constraints: {any non-negotiables}
Does this capture it?"
Wait for explicit confirmation before proceeding to analysis.
- Green signal: Proceed to Phase 3
- Yellow signal: Clarify and adjust understanding
- Red signal: Return to discovery questions
Check if brief is over-specified (bypasses learning opportunities).
- Specific technology mentions (React, Laravel, PostgreSQL)
- Implementation patterns ("use async/await", "REST API", "microservices")
- Technical architecture details (database schema, API structure)
I noticed your brief mentions specific technologies...
Options:
- A) Continue: Use brief as-is (I'll still recommend best approach)
- B) Revise: Refocus on problem/goals, let me recommend stack
- C) Restart: Create new brief from scratch
- D) Discuss: Talk through the trade-offs together
Your choice?
Generate comprehensive recommendation. Remain deployment-neutral.
See DECISION-FRAMEWORKS.md for detailed frameworks and patterns.
1. Primary Recommendation: Best-fit tech stack with detailed rationale
2. Alternative Options: 2-3 viable alternatives with trade-offs
3. Ruled-Out Options: Stacks that don't fit and why
4. Tech Stack Details: Complete breakdown (NO deployment/hosting details)
5. Learning Opportunities: What this stack will teach
6. Enterprise vs Hacker Analysis: Where each option falls on the spectrum
7. Decision Rationale: Why this choice, what was considered
8. Next Steps: Invoke deployment-advisor (deployment decisions happen THERE)
This skill focuses ONLY on technology stack decisions (languages, frameworks, databases, patterns).
- Do NOT factor in hosting infrastructure when recommending stacks
- Do NOT mention specific servers, VPS specs, or deployment targets
- Do NOT let "we already have X infrastructure" bias the tech recommendation
- The deployment-advisor skill handles all hosting/infrastructure decisions AFTER this phase
- Exception: If user EXPLICITLY states a deployment constraint, note it in handoff but still recommend the best technical solution
Create .docs/tech-stack-decision.md handoff document.
"Ready to lock in this tech stack choice?"
Wait for explicit confirmation before creating handoff.
- Handoff artifact for deployment-advisor
- Session bridge for fresh sessions
- Decision record for future reference
.docs/tech-stack-decision.md
Create .docs/ directory if it doesn't exist before writing handoff document.
Add "Decision Rationale" section to handoff:
- Chosen: {stack} because {reasons}
- Alternatives considered: {stack} - not selected because {why}
- Reversibility: Easy / Moderate / Difficult to change
If user explicitly mentioned deployment preferences or constraints:
- Document in "User-Stated Constraints" section
- Let deployment-advisor reconcile tech stack with deployment realities
Validate understanding based on PROJECT-MODE.md setting (or gathered mode preference).
Answer 3 focused comprehension questions:
1. Why does the primary recommendation fit this project's core need?
2. What is the single most important trade-off if you chose Alternative 1 instead?
3. What is the biggest new responsibility or learning challenge this stack introduces?
Rules:
- Short but complete answers acceptable
- Question-by-question SKIP allowed with acknowledgment
- NO global bypass (can't skip all)
- Educational feedback provided on answers
Simple self-assessment checklist:
- [ ] I understand the primary recommendation and why
- [ ] I've reviewed the alternatives and trade-offs
- [ ] I understand how this fits my learning goals
- [ ] I'm ready to move to deployment planning
Confirm to proceed.
Quick acknowledgment: "Ready to proceed? [Yes/No]"
Factor in user's experience and learning goals. Remain deployment-neutral.
- Beginner-to-intermediate developer
- Strong with HTML/CSS/JavaScript
- Learning full-stack development
- Heavy reliance on Claude Code for implementation
If skill_guidance.preferences loaded from registry:
- Use as context for recommendations
- Still explain trade-offs
PREFERRED DEFAULT for most projects:
- Full PostgreSQL features + BaaS conveniences
- Auth, storage, realtime included
- pgvector for AI/embeddings
- $0 marginal cost on existing infrastructure
Consider when:
- Simple auth is primary need
- SQLite scale appropriate
- Single-binary simplicity valued
Rule out when:
- Vector embeddings required
- Complex relational queries needed
- PostgreSQL-specific features required
- Run Phase 0 to load environment registry (graceful degradation if missing)
- Use Lightweight Discovery before recommending
- Wait for approval gates (understanding, handoff)
- Ask clarifying questions (don't guess)
- Consider user context (experience, learning goals) — but NOT infrastructure
- Provide rationale (teach decision-making)
- Show alternatives with trade-offs
- Be opinionated but not dogmatic
- Include Enterprise vs Hacker analysis for each recommendation
- Include decision rationale in handoff
- Create .docs/tech-stack-decision.md handoff document
- Gather missing prerequisites conversationally (never block)
- If user states deployment preferences, document in "User-Stated Constraints" section
- Keep recommendations deployment-neutral
- Skip Phase 0 environment loading
- Skip discovery approval gate
- Skip handoff approval gate
- Proceed on silence (always wait for explicit confirmation)
- Skip handoff document creation
- Let infrastructure availability bias tech stack recommendations
- Make implementation decisions (CONSULTANT role)
- Push to next phase without checkpoint validation
- Block on missing prerequisites (gather info instead)
- Include hosting providers, server specs, or deployment strategies
- Factor in "we already have X" when recommending tech stacks
- Access registry data outside allowed paths
CRITICAL: This skill recommends WHAT to build with (languages, frameworks, databases).
The deployment-advisor skill recommends WHERE to run it (hosting, infrastructure, servers).
These concerns must remain separated to ensure unbiased tech stack recommendations.
Phase 1 of 7: Technology Stack Selection
Status:
Phase 0: Project Brief (project-brief-writer)
Phase 1: Tech Stack Advisor (you are here)
Phase 2: Deployment Strategy (deployment-advisor)
Phase 3: Project Foundation (project-spinup) <- TERMINATION POINT
Phase 4: Test Strategy (test-orchestrator) - optional
Phase 5: Deployment (deploy-guide) <- TERMINATION POINT
Phase 6: CI/CD (ci-cd-implement) <- TERMINATION POINT
Phase 1 of 7 in the Skills workflow chain.
Expected input: .docs/PROJECT-MODE.md, .docs/brief-*.md (gathered conversationally if missing)
Produces: .docs/tech-stack-decision.md for deployment-advisor
This skill can be invoked standalone without prior phases. Missing context is gathered through conversation rather than blocking.
For detailed decision frameworks, patterns, and templates, see [DECISION-FRAMEWORKS.md](DECISION-FRAMEWORKS.md).
Users can invoke the **workflow-status** skill at any time to:
- See current workflow progress
- Check which phases are complete
- Get guidance on next steps
- Review all handoff documents
Mention this option when users seem uncertain about their progress.
