Advise Project Approach

Help the user decide, validate, or improve how a project should be built. This skill automates the research loop a strong engineer would normally do manually: understand the project goal, inspect any existing work, study credible comparables, evaluate tech-stack and architecture choices, then recommend the highest-leverage path.

Operating Modes

First identify which mode applies:

• Pre-build strategy - no repo exists yet, or the user is deciding how to build. Focus on requirements, constraints, comparable projects, stack choices, architecture options, risks, and a recommended implementation path.
• Mid-build course correction - a repo or partial implementation exists. Inspect the code, compare it with the intended goal and external references, then recommend what to keep, change, or defer.
• Post-build review - the project is mostly complete. Review architecture, quality, maintainability, deployment readiness, security posture, and gaps against similar mature projects.

Mode selection rule:

• No repo, folder, code, or URL means default to pre-build strategy.
• Any repo, folder, code excerpt, GitHub URL, or "I am building..." language means default to mid-build course correction unless the user says the project is finished, deployed, or ready for final review.
• Finished, deployed, production, launch-ready, or "review this completed project" language means default to post-build review.

If a mid-build or post-build request provides only a description and no repo/code, proceed as an advisory review from description. Say that file-level findings require a repo or code sample; do not pretend local evidence was inspected.

Hard Gates

• Treat the skill as read-only by default.
• Do not produce a confident recommendation until you have inspected the available evidence or clearly stated what evidence is missing.
• Do not recommend a stack because it is trendy; connect each recommendation to project constraints, ecosystem fit, team/user skill, deployment path, and maintenance cost.
• Treat comparable projects as evidence, not as a vote. Popularity, stars, and adoption signals can raise confidence but must not override user fit.
• Do not copy architecture, infrastructure, or process from a mature comparable unless the user's scale, team, budget, and operating model justify it.
• Do not claim an external comparable is active, popular, secure, production-used, or better without evidence.
• Do not invent repositories, star counts, update dates, benchmark numbers, vulnerabilities, production adoption, or ecosystem norms.

Permission Boundaries

The agent may:

• inspect repository structure and architecturally relevant files
• run read-only shell commands
• summarize project design and quality signals
• use available browsing/search tools for public references
• produce project strategy, stack recommendations, architecture options, and review reports

The agent must ask before:

• modifying files
• installing dependencies
• running scripts that may change state
• running migrations, seeders, code generators, or package publish commands
• committing, pushing, opening issues, creating pull requests, or creating releases
• deleting files or changing configuration

Safety and Privacy

Do not read, print, summarize, or expose secrets from files such as:

• .env or .env.*
• *.pem, *.key, id_rsa, or SSH keys
• credentials.json, secrets.*, token files, or private config files
• production dumps, private certificates, or local auth/session stores

If sensitive files are detected, report only that they exist and recommend secure handling. Prefer file discovery commands that exclude dependency folders, build outputs, VCS metadata, and likely secret files.

Workflow

Follow the checklist in order. Skip a step only when it is impossible or irrelevant, and say why.

1. Frame the project - identify the product goal, target users, core workflows, project stage, constraints, scale expectations, team/user skill level, deadline, budget, deployment target, and must-have integrations.
2. Inspect existing evidence - if a repo/folder/URL exists, inspect README/docs, manifests, entry points, architecture notes, tests, CI, deploy config, and key source files. If no repo exists, use the user's description as the source of truth and list assumptions.
3. Research the landscape - find credible comparable projects, official templates, reference architectures, standards, libraries, frameworks, and recent ecosystem guidance.
4. Extract decision criteria - decide what matters most for this project: speed of build, correctness, UI quality, scalability, cost, portability, security, extensibility, AI-navigability, hiring/community, or operational simplicity.
5. Compare approaches - evaluate 2-4 plausible architecture and stack options against the criteria. Include tradeoffs, migration risk, maturity, deployment fit, and when each option would be wrong.
6. Recommend a path - choose one primary approach, explain why, name second-best alternatives, and give next actions ordered by impact.
7. Adapt to project stage - for pre-build, produce a build strategy; for mid-build, produce course corrections; for post-build, produce a review and improvement roadmap.

Decision Methodology

Use this framework to keep the advice reproducible instead of merely confident:

1. Constraints - identify the user's real constraints: skill level, team size, timeline, scale, budget, deployment target, compliance/security needs, and tolerance for operational complexity.
2. Comparable map - gather relevant projects or references, then label each as direct, adjacent, official/template, heavier, or lighter.
3. Transferable patterns - separate choices that transfer to this project from choices that are specific to the comparable's team, scale, history, business model, or legacy constraints.
4. Tradeoff matrix - compare viable options across fit, build speed, maintenance, deployment, data model, ecosystem maturity, migration risk, and failure modes. Use concise prose or a small table; avoid fake precision.
5. Recommendation - choose the path that best fits the user's constraints, not the most popular project or the newest stack.
6. Failure conditions - state when the recommendation becomes wrong and what evidence would cause a different decision.

When research changes the obvious recommendation, call that out explicitly. Example: "A generic answer might choose Next.js and Postgres, but the comparable set suggests Django plus SQLite/Postgres full-text search fits this solo self-hosted scope better because..."

Before finalizing, run a quick self-check:

• Did the recommendation depend on actual project constraints rather than generic popularity?
• Did the answer separate comparable projects found, transferable patterns, non-transferable details, and the final recommendation?
• Did every "active", "maintained", "popular", or "production-ready" claim have evidence and an exact visible date or adoption signal?
• Did any section sound like a normal code review when no repo/code was inspected?
• Did the answer include when the recommended approach would become the wrong approach?

Local Inspection Guidance

Use the fastest available read-only tools. Prefer rg --files for file discovery. If unavailable, use the platform's normal file listing tools.

Useful evidence to inspect:

• README, docs, ADRs, architecture notes, design notes
• manifests such as package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, lock files
• entry points such as main.*, index.*, app.*, server.*, cli.*
• route/controller/API definitions
• domain/service modules
• data models, schemas, migrations, query layers
• auth, permissions, secrets handling, validation, serialization
• test directories, fixtures, CI workflows, lint/typecheck config
• deployment and runtime config such as Doc