📦 Reading Beta docs (0.5 track). Check your install: trellis --version. Install latest: npm install -g @mindfoldhq/trellis@beta. Switch to Release in the version dropdown ↘
Use Trellis in real engineering work: new products, brownfield repos, refactors, migrations, bug fixes, and team rollouts.
Most teams do not need another command list. They need a way to keep project decisions from disappearing between AI sessions: new projects need early rules before patterns spread, brownfield repos hide conventions in old PRs, refactors need invariants, migrations need batches, and production bugs need lessons that survive the fix.Each scenario below gives a starting prompt, the Trellis files to produce, the workflow to follow, and a concrete finish line. Pick the closest situation and adapt it into a task for your repo.
Trellis 0.5 is skill-first. Treat the prompts below as task inputs; Trellis routes the work
through the relevant skills for brainstorming, spec loading, checks, and knowledge capture. Use
/trellis:start only when your platform needs a manual session entry point.
Make adoption consistent across developers and agents
For the first week, optimize for one useful task, not a complete framework rollout. A small
working spec and a clear task PRD teach the team more than a large empty spec library.
Use this when you are creating a product, service, package, or internal tool from zero. The risk is that early AI output creates accidental conventions before the team has named them.
You are starting a B2B dashboard with authentication, team management, billing, and analytics. You want AI to help build quickly, but you do not want every session to invent a new folder layout, API style, or component pattern.
I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.First, ask for the missing product and tech-stack decisions. Then create a small first-task PRD andthe minimum specs needed for frontend structure, API shape, error handling, and tests.
Initialize Trellis after the repo and package manager exist.
Ask the AI to draft only the specs needed for the first week.
Edit those specs manually. Remove guesses, vague rules, and future plans.
Create one task for the smallest useful vertical slice.
Build that slice with check and finish steps enabled.
Record the session so stack decisions and tradeoffs are easy to recover.
trellis init -u alice/trellis:start"Create the first task for project foundation. Keep scope to auth shell, app layout, lint/typecheck/test commands, and one sample route."
You inherit a three-year-old SaaS repo. There are many patterns for API routes, permissions, and forms. AI can make local changes, but it often misses project-specific details.
This is an existing repo. Do not refactor code yet.Inspect the codebase and propose a minimal Trellis bootstrap for the next feature task. Identify theactual patterns used for API routes, auth checks, logging, tests, and frontend forms. Write specs onlyfor patterns supported by current code examples.
You need to add team invitations. The feature touches workspace permissions, invitation emails, API routes, database tables, frontend forms, and edge cases such as expired invites.
Create a Trellis task for team invitations.The feature should let workspace admins invite users by email, resend pending invites, revoke invites,and accept an invite. Include product requirements, out-of-scope items, data model changes, API shape,frontend states, tests, and rollout risks.
# Team Invitations## GoalWorkspace admins can invite teammates by email and manage pending invites.## In scope- Create invite- Resend invite- Revoke invite- Accept invite- Expiration handling## Out of scope- Bulk CSV import- SSO provisioning- Role templates## Acceptance criteria- Non-admin users cannot create, resend, or revoke invites.- Expired invites show a recoverable error.- Invite acceptance is idempotent.- Tests cover permission checks and expired invite behavior.
src/billing/invoice-service.ts has grown to 1,200 lines. It calculates invoices, applies discounts, calls payment APIs, writes audit logs, and formats email content. You need to split it without changing billing behavior.
Create a behavior-preserving refactor task for src/billing/invoice-service.ts.First map current responsibilities, callers, side effects, and existing tests. Then propose the safestsequence. Do not change behavior until we have characterization tests or clear existing coverage forthe important billing paths.
## Behavior that must not change- Invoice totals must match existing calculation for active discounts.- Failed payment attempts must still write audit logs.- Email rendering output must remain byte-for-byte compatible for existing templates.- Public API response shape must not change.
Tests prove the old and new behavior match for important paths.
The diff is reviewable by responsibility, not a giant rewrite.
New module boundaries are documented for the next AI session.
No opportunistic feature work is mixed into the refactor.
If the AI proposes “modernizing” unrelated code during a refactor, move that work to a separate
task. Refactors fail when behavior preservation and product changes are mixed.
Use this when the same change needs to happen across many files: framework upgrade, API client replacement, design system migration, lint rule adoption, dependency removal, or test runner migration.
You need to migrate frontend data fetching from direct fetch() calls to a shared typed API client. The repo has dozens of call sites and several edge cases.
Plan a Trellis migration from direct fetch calls to the shared API client.Find call-site patterns, group them by risk, choose a small pilot batch, define verification commands,and create separate tasks for low-risk, medium-risk, and high-risk files. Do not migrate everything inone PR.
Users can submit checkout twice when the network is slow. The immediate fix is button state, but the deeper issue is that submit flows do not share a consistent idempotency and UI-state rule.
Fix the duplicate checkout submission bug.Reproduce the issue, identify the smallest safe patch, add a regression test, and then run abreak-loop analysis. If the root cause is a missing convention, propose a spec update.
Convert the prevention into a spec, test helper, or checklist.
Record the session so the reasoning survives.
/trellis:start"Users can submit checkout twice when the network is slow. Reproduce it, fix it, and add a regression test."Ask Trellis to run break-loop analysis.
Use this when reviewers keep writing the same comments: missing loading states, inconsistent errors, no regression tests, unsafe SQL, custom date formatting, or new helpers that duplicate existing utilities.
Review the last few PR comments and help me convert repeated engineering feedback into Trellis specs.Only propose rules that are concrete, enforceable, and tied to actual review comments. For each rule,show the target spec file and a good/bad example.
Split this work into parallel Trellis tasks.Identify dependencies, files likely to conflict, suggested branch names, PRD summaries, and the orderin which the PRs should be reviewed. Only parallelize tasks that can be reviewed independently.
A 50-person engineering department has Claude Code power users, Cursor users, and developers experimenting with other AI tools. Leadership wants shared conventions and reviewable AI work without forcing everyone into one IDE.
Create a Trellis rollout plan for one pilot repo and one department.Include pilot criteria, first specs, task workflow, review policy for spec changes, platform adaptersetup, success metrics, and risks. Keep the first rollout small enough to complete in two weeks.
