I have a new idea
Empty folder, no code
npx tillerhand initin the folder- New session in the same folder,
/start your idea: a plan in nine steps - Phase 0: CI and the first deploy
- Every day
/build: the next task
v3.49.1 Starter kit for Claude Code · MIT
The AI builds.
The AI builds.
You steer.
TillerHand takes a product from idea to production and maintenance with Claude Code. At every important decision the AI gives you the options, its recommendation and the cost of each option. An expert board reviews the work, and guardrails stop mistakes before they happen.
npx tillerhand init
Where:
Run it in the project folder. Then open a new session in the same folder and type /start your idea.
One command is enough; the plugin and git routes are in Setup · Also works in Codex and Antigravity · No coding knowledge needed
› /start Invoice tracking for freelancers
Step 4/9 · Technology · This decision shapes the whole data layer; changing it later is expensive.
Which database and authentication should we use?
Supabase (Recommended)Postgres, auth and file storage in one place. Row-level security is ready; the free tier is enough for an MVP.
Neon + Better AuthMore control, less dependence on one provider. The auth code stays with you.
FirebaseReal-time and a shared backend with mobile. NoSQL; weak relational queries.
Board opinion: Architect ✓Security ✓Cost: watch
Why
Writing code with AI is fast. Shipping a product is a different job.
With "vibe coding" a demo takes an afternoon. A product that real users touch can't survive silent decisions, untested code, leaked keys and a messy folder tree. TillerHand keeps the speed and closes these four gaps.
UsuallyThe AI picks the database, the library and the data model on its own. Nobody knows why.
With TillerHandEvery decision comes to you with 2-4 options: the recommended one first, with when each is better and what it costs. Your answer goes into the log and is never asked again.
Usually"It works" is the only proof, and there are no tests. The next change breaks the last one.
With TillerHandAcceptance tests are written before the code and start red. Before "done", proof is shown: test output, a screenshot.
UsuallyAn API key lands in the code, the prod database gets deleted by accident, a test is weakened so it passes.
With TillerHandHooks stop these before they happen. The AI can't bypass these guardrails; every step toward prod needs your approval.
UsuallyThree months later nobody knows where the files are;
final-v2-old.tsx multiplies.With TillerHandA feature-based folder map is enforced when files are written, in CI and in review. Clutter files are blocked.
How it works
The same cycle for every task. You sit in the middle.
TillerHand is a way of working, not a list of commands. You write your idea and walk through the rest with the AI, step by step. Nothing important happens without you knowing.
- 1
The AI plans
Reads the task, finds the decision points, prepares the options.
- 2
You decide
Recommended option first; when each is better, and what it costs.
- 3
Test first, then code
A separate agent writes the tests and they start red; the code turns them green.
- 4
The board reviews
The relevant experts review; a critical finding means the task is not done.
- 5
Saved with proof
If the gate is green: commit, dashboard update, next task.
↺ Repeats for every task · findings reports and a board meeting at the end of a phase
You make the decisions
Product, technical, design, data, security and cost decisions are asked with reasoned options. Design questions come with a visual preview using real content.
The expert board reviews
Members such as Product, Architect, Security, UX, Privacy (KVKK) and QA review the plan, the task, the commit and the phase. For key decisions a council of different models meets.
Guardrails stop mistakes
Secret block, destructive command shield, package gate, test protection, commit gate. The rules are written, the checks are automatic; the AI can't bypass them.
You always know where you are
A status block at the end of every answer, the task and limit in the status line, a live control panel in the browser.
Scans like an expert
The 20 most important findings for tech, business, security, UX, performance and legal; with evidence, a score and a fix.
To production and beyond
Hosting, domain and backup setup step by step; approved prod deploys; live monitoring and regular maintenance.
At work
This is what a day with TillerHand looks like.
These are simplified versions of real output. All of it happens inside a Claude Code session, in the chat.
MEMBER: Security · VERDICT: REJECT FINDINGS: [CRITICAL] app/api/invoice/[id]/route.ts:14 The invoice owner is not checked; another user's id reads their invoice. → Add a user_id condition to the query. MEMBER: QA · VERDICT: APPROVE ASK THE USER: none
The board catches a hole
With a critical finding (REJECT) the task is not done. You get three paths: fix it, accept the risk with a reason, or roll the task back.
Write lib/stripe.ts BLOCKED: a secret is being written to lib/stripe.ts (Stripe secret key). Do not write the secret in code; read it from an environment variable and add its name to .env.example with an empty value. Bash vercel deploy --prod APPROVAL NEEDED: Deploy to the prod environment.
Guardrails stop the mistake before it happens
The block comes inside the chat, with an explanation. Every step that touches prod, data or money waits for your approval.
── Status ──────────────────────
Phase: 1 · Task: G-012 (7/23) · Question mode: open · Limit: 5h 34% weekly 5%
Done: signup form + validation, tests green · Board: APPROVE (ux, qa) · Auto decisions: none
Next: G-013 password reset · pending decision: email service
You always know where you are
Phase, task, limit, the board's verdict and the next step at the end of every answer. When you come back after a break, your place is ready.
Now · Phase 1 · G-012 signup form
Attention: 1 critical findingdomain: 21 days2 decisions pending
The whole project on one page
Decisions, board, findings, quality, operations and limit; it updates itself after every Claude answer.
Results
The difference is in the tests that catch bugs.
The same tasks ran with and without TillerHand through claude -p and were scored with hidden tests. Then bugs were injected into the code on purpose: do the tests the agent wrote catch them?
24/24
With TillerHand the tests came before the code in every run. Without the kit, in none.
81/81
Both conditions passed every hidden test; the model solves tasks of this size without the kit too.
48
Runs: 6 different tasks (bug fix, new feature, authorization security, pagination, Turkish sorting and a trash bin); 24 runs per condition.
Version 3.18.2 · Sonnet · 6 tasks · 24 runs per condition. The setup and results are in the repo: kit/eval/.
Guide
The full guide
Everything from setup to maintenance: commands, board, guardrails, tools and rules.
Before you start
Setup
Pick your path first: are you starting a new idea in an empty folder, or do you already have code? The install is the same for both; what changes is the command you type after it.
I already have code
A project that is under way, that you don't like, or want to bring into order
npx tillerhand initin the project root; your files are not overwritten- New session,
/adopt: the code is scanned, the docs are derived from it - Tests for the critical flows first
- Alignment tasks with
/build, feature by feature
Requirements: Claude Code, Git, Node.js 18+.
For the install, pick one route; all three copy the same files into the project (.claude/, CLAUDE.md, AGENTS.md, docs/) and create a git repo if there isn't one. If you're unsure, use npm. The project type is not asked at install, but during /start.
| Route | When |
|---|---|
| 1. npm (recommended) | The shortest route. In the terminal, or by telling Claude "run npx tillerhand init in this folder" |
| 2. Claude Code plugin | Installed once on the computer, then /tillerhand:init in every new project. The plugin only does the install and fetches the latest version each time |
| 3. git | To see the kit's source, change it or contribute. The kit sits in the project in a vibe-kit/ folder and goes into .gitignore |
# 1. npm: in the project folder npx tillerhand init # 2. plugin: once (if /plugin does not open on the desktop, in the terminal: claude plugin marketplace add … and claude plugin install …) /plugin marketplace add burakdogrul/TillerHand /plugin install tillerhand@tillerhand # then in every new project: /tillerhand:init # 3. git: in the project folder git clone https://github.com/burakdogrul/TillerHand.git vibe-kit node vibe-kit/kit/kit.mjs init
After the install, open a new Claude Code session in the same folder; the kit's commands and guardrails load in the new session. Then /start your idea in a new project, or /adopt in an existing one.
Which tool:
init asks which of Claude Code, Codex and Antigravity you will use (one or more). You can also pass it directly: init --tool codex. If the kit is in another folder: node <kit>/kit/kit.mjs init --project <project>. For the Turkey add-on use --addons tr.Plugins: When the project opens for the first time, Claude Code offers to install the skill plugins defined in
.claude/settings.json: Caveman, Impeccable, Taste Skill, UI UX Pro Max, Humanizer, Ponytail and Matt Pocock. /start installs the missing ones at project scope with your approval (plugins-sync.mjs --install). The design, security, release and video packs are installed but stay off; the related command asks to turn them on when needed.Recommended: the code map. If codebase-memory-mcp is connected, the AI queries the code instead of reading it file by file; as the project grows this saves a lot of tokens.
/start asks whether you want it; you do the install in your own terminal.Without coding
If you're new: step by step
You don't need to know how to code. Claude does the git, terminal and install work and asks you at every important step. You describe what you want and make the choices.
- Accounts (once): a GitHub account (free) and a Claude Pro or Max subscription.
- Programs (once): the Claude desktop app, Node.js (LTS version), Git. You can also install GitHub Desktop if you like.
- Project: Create a folder for your project and select it in the Code tab of the Claude desktop app. Tell Claude "run
npx tillerhand initin this folder". If you've installed the TillerHand plugin once,/tillerhand:initworks too. - Open: Open a new session in the same folder; the kit's commands and guardrails load in the new session. If it offers to install the plugins, accept.
- Start: Type
/start your idea(or/adoptif you already have code). The first option of every question is the recommended one; if you're unsure, pick it. If you're on Pro, suggested answers for the first questions: profile Light, planning depth Quick (~25-35% of your 5-hour limit), dashboard Yes, narrator mode Yes.
Good to know. Pro has a 5-hour and a weekly usage limit; Claude warns at 90%, 95% and 99% but does not stop the work. If the limit runs out and the work is cut off, you continue from where you left off with
/build after it resets. Decisions such as database, design and cost are never made without asking; hard-to-undo steps such as payment, data deletion and going live always need approval. To hand the project to someone else use /handoff; the new owner continues from the same place with /handoff take.If you already have code
/adopt: bring an existing project into the kit
The counterpart of /start for existing code. It starts from the code, not from an idea, but you still make the decisions. This session does not touch the application code or move files; moving and fixing happen later as /build tasks.
# in the project root npx tillerhand init # new session in the same folder /adopt
1
Read-only
Scans
The stack, folder structure, features, test status and the last 30 commits are extracted. A quick scan costs about 10-20% of the 5-hour limit; a deep scan also runs the findings reports you choose.
2
With your answers
Derives the docs from the code
The PRD, stack and architecture are drafted from the code, and anything unclear is asked: what don't you like, what do you want to improve? The rules in the old CLAUDE.md are asked one by one and moved to AGENTS.md. If a kit file clashes with one of the project's, it is placed next to it as .kit-new and the merge is asked.
3
Before moving
Tests for the critical flows
3-7 flows such as login, payment and data saving are chosen, and the correct behavior of each is asked from you. The test is written from your answer, not from what the code does today; if the two conflict, it becomes a finding.
4
Roadmap
Alignment tasks
Phase 0 safe groundPhase 1 move the structurePhase 2 findingsPhase 3 new features
The structure is moved on a separate branch, feature by feature. After each task the tests and the app must still work; if something breaks, /rollback. Then /build as every day.
Routine
Every day
| When | What you type |
|---|---|
| When you start work | /build: you don't need to type a task code; it takes the next task itself and tests it |
| If you wonder about the status | where are we? or /dashboard |
| If something breaks | /rollback: safely returns to the last working state |
| If you see a bug | /fix-bug symptom: finds the root cause, writes a red test first, then fixes it |
| When you stop | /wrap-up (saves everything), then /clear. On a clean screen the next command is written |
docs/workflow/decision-protocol.md
You make the decisions
Every choice about product, tech, design, content, data, security and cost is a decision point. The AI prepares the options, puts its recommendation first, and writes when each option is better and what it costs. Your answer is saved to docs/decisions/log.md, then applied, and never asked again.
Phase: Setup 4/9 · Technology. This decision shapes all the backend code; changing it later is expensive.
Which language and framework should we write the backend in?
Python + FastAPI (Recommended)Your idea involves reading documents and AI summaries; Python has the strongest ecosystem for that.
Node.js + HonoIf the frontend is TypeScript too, you get one language and shared types.
GoIf you need very high traffic and low server cost; development is slower.
| What you say | What happens |
|---|---|
| "don't ask about design" | Only the design topic is closed. The AI picks the recommended option, records the decision as "automatic" and reports it in the status block. Previews are still produced. |
| "don't ask anything" | All topics are closed. |
| "ask again" | The topic(s) reopen. |
/ask-mode | Shows the current mode and the automatic decisions; changes it with on / off <topic>. |
| Topic | Example decisions |
|---|---|
| product | MVP scope, priority, user flow, price |
| tech | Language, framework, database, auth, hosting, adding a library, API style |
| design | Style direction, color, typeface, layout, component style, animation, dark theme |
| content | Copy, tone of voice, formal/informal address, headline and CTA alternatives |
| data | Data model, delete behavior, retention period |
| security | Roles, session length, rate limits, personal data |
| cost | Paid service, plan tier, AI model, spending limit |
For hard-to-reverse decisions (database, auth, payment, data model; a "one-way door") the board's opinion, and if needed the council's, is taken first. Whatever the question mode, approval is always asked for: data deletion, deploys to prod, anything that spends money, irreversible commands. Implementation details such as file and variable names are not asked, only reported.
.claude/commands/start.md
/start: the nine-step wizard
It makes all the basic decisions of the project without writing application code. Decisions are written to the log the moment they are made and show up on the dashboard. If it stops halfway, it continues from the step it reached.
| Step | What happens | Example question | Skill |
|---|---|---|---|
| 0 Preparation | Profile (Light / Standard / Full), planning depth (with its cost), tool, dashboard, node, git, skill, limit and code map checks | "Planning depth: Quick (~25-35%) / Standard (~50-70%) / Detailed (~80-100%)?" | caveman |
| 1 Idea | The idea is questioned in rounds, the PRD is written | "Which features should the first version have?" (multi-select; unselected ones are out of scope) | grilling |
| 2 Type | Web/SaaS, mobile or backend; whether there is an AI feature | "Your users work at a desk; I recommend web. Does that fit?" | - |
| 3 Install | node kit/kit.mjs install places the type and the folder map | - | - |
| 4 Technology | The 10-12 decisions in the type's decision catalog, one by one | "Database and auth: Supabase / Neon + Better Auth / Firebase?" | research |
| 5 Architecture | Data model, login methods, roles, services and cost, glossary, unit economics | "Should a deleted invoice go to the trash or be deleted permanently?" | domain-modeling, codebase-design |
| 6 Board | The expert board suggested for the type; members work with the review role's model, and the agents are generated in the project. An expensive step: cost first, then "Do it / Do it light / Leave for later" | "Who should be on the board?" (multi-select) | - |
| 7 Design | /design general: style, color, typeface and details through visual previews. An expensive step: the cost is asked first | "Which of these three landing pages?" | taste, impeccable, ui-ux-pro-max |
| 8 Roadmap | Tasks with the acceptance test first, the first feature, the launch goal | "Which feature should we start with in Phase 1?" | - |
| 9 Wrap-up | Summary, steps left for later, the first task | - | - |
When the stack is chosen, the Requirements/Setup section of the project's README and the version file (
.nvmrc / .python-version) are filled in; the project can be set up the same way on another computer. /release and the monthly /maintain test this by installing it in a clean folder./design · visual preview
You choose design by seeing it
For every design decision, a sample with real content is produced for each option (.previews/), opened in the browser, and a screenshot is shown; then you are asked. Each style direction is drawn with its own skill, so the differences between the options are real.
Style direction · 3 samples→
Color · 3 palettes→
Typeface · 3 pairs→
Details→
DESIGN.md→
Page structure→
Copy + humanizer→
Apply→
critique · audit · polish
Premium / Apple style
taste-skill:high-end-visual-design
- Lots of space, large and thin type, soft transitions
- Consumer product, brand perception, high price
Minimal editorial
taste-skill:minimalist-ui
- Warm monochrome, type-driven, flat surfaces
- Content, portfolio, calm SaaS
Bold and animated
taste-skill:gpt-taste
- Giant type, scroll-driven animation, bento
- Launch page, young audience
Industrial / brutalist
taste-skill:industrial-brutalist-ui
- Raw grid, terminal look
- Developer tool, data-dense dashboard
Functional product UI
impeccable + ui-ux-pro-max:ui-styling
- Plain, information-dense, fast to use
- Panel, admin, B2B tool
Common to every direction
impeccable · ui-ux-pro-max · humanizer
- PRODUCT.md and DESIGN.md in Impeccable
- Palette and typeface candidates from UI UX Pro Max
- Copy passes through Humanizer
Inspiration brand (optional): The DESIGN.md of a product you like (awesome-design-md) is downloaded and its principles are distilled with Impeccable. The logo, name and exact palette are not taken; there is no brand imitation.
After /start
Four stages
Every stage has an exit gate: you don't move on to the next one until the items at the gate are complete.
1
Day one · Phase 0
Setup and first deploy
/build G-001… G-007CI greenprod URLSentrytokens in code
Exit gate
- dev, test, lint and build commands work
- A trial commit containing a secret is rejected, CI is green on GitHub
- "Hello world" opens at the prod URL, error tracking works
2
Every task · Phase 1–2
Development cycle
/plan-task · decision points are asked→
/build · test-writer writes the tests→
proof→
/review-changes→
gate + board → commit→
/wrap-up
Definition of "done"
- All decisions that came up in the task were asked and recorded
- Tests are green, proof that it works was shown
- If there is an interface: it matches DESIGN.md, an Impeccable critique was done, the copy passed through Humanizer
- No REJECT in the task-end board meeting
3
Launch · and every release
Going live
/release first/releasesecurity-auditorsecurity-reviewponytail-auditimpeccable audit
/release first walks you through the hosting, environment variables, domain and DNS, backup and point-in-time recovery (PITR), and rollback rehearsal for your provider (Vercel, Supabase, Railway, EAS) at the first launch. The steps come from the official docs, with source and date; you enter the secret in the dashboard of the provider.
Exit gate
- All ❌ items are closed; the things you need to check were asked
- A restore from backup was tried, the rollback path is written down
- KVKK texts are published, spending limits are set, live monitoring is on
4
While live · regularly
Maintenance
/maintain weeklymonthly · ponytail-debtquarterly · ponytail-audit/user-feedback/retro
Live monitoring tests a critical flow and the response time every 3 hours; when it breaks, a GitHub issue is opened, a warning shows on the dashboard and /fix-bug is suggested.
In an incident, in order
- Stop, Record, Fix, Notify (the KVKK Board within 72 hours for a personal data breach), Learn
.claude/agents/board-* · docs/workflow/board.md
Expert board
Expert agents are created in your project for the product type you choose and tailored to the stack. They review the work continuously, recommend decisions and keep you informed. They are advisors; they stop the work only on a critical finding. The decision is always yours.
Web / SaaS
product · architect · security · ux · performance · privacy · qa
- + devops, + ai (if there is an AI add-on)
Mobile
product · architect · security · ux · mobile · privacy · qa
- + devops, + ai
Backend
product · architect · security · api · devops · qa
- + privacy (if there is personal data), + ai
| Meeting | When | Who | Model |
|---|---|---|---|
| Plan · council | At the end of /plan-task, before approval | Product + Architect + relevant members (at most 4) + chair | review role · chair opus |
| Task end | At the end of /build | Relevant members (at most 3) | review role |
| Commit (light) | Before every commit; the hook enforces it. Skipped if the task-end meeting approved the same changes | At most 2 relevant members, only files changed since the last approval | haiku |
| Phase end · going live | /board convene, /release first | The whole board + chair | review role · chair opus |
| Decision council | A one-way door decision, /board council | 3 advisors answer the same question + chair | haiku · sonnet · opus · chair opus |
Council: three stages
Karpathy's llm-council structure, adapted to the board. Heavy meetings and decisions that are expensive to reverse go through three stages:
1 · First opinions
Members (or advisors on different models) work in parallel without knowing about each other. Opinions are labeled A, B, C; findings A1, A2…
2 · Anonymous cross-vote
Each member reads the others' opinions without knowing who wrote them, votes each finding AGREE · OVERSTATED · DISAGREE, writes what is missing, and ranks the opinions.
Count (code)
council.mjs computes the average rank, the finding votes and the consensus percentage in code; the model can't change the numbers.
3 · Chair
board-chair (opus) reads the minutes, writes the decision, drops refuted findings with a reason, and keeps the minority opinion. It can't drop a disputed critical finding; it asks you.
The profile decides when the council meets (one council costs about 12% of the 5-hour limit on Pro):
| Light (recommended for Pro) | Standard | Full | |
|---|---|---|---|
| Plugins | Core 6 + the type's LSP and stack skills | Core 8 + stack; packs when needed | Core 8 + stack; packs when needed |
| Commit review | Off | On | On |
| Command list | 10 core commands with descriptions, the rest by name only (~1,100 tokens less) | Like Light | All with descriptions |
| Meeting council | None | Phase end, going live | Plan, phase end, going live, REJECT |
| Decision council | Database, auth | Database, auth | All one-way decisions |
The "(Recommended)" option of a question asked in the decision council comes from the council; under each option you see the council's vote and the minority opinion. Minutes are in docs/workflow/council/, with a summary in the dashboard's Board tab.
When a REJECT comes, the task is not counted as done. You get three options: fix it (recommended), accept the risk and record the reason, or roll the task back. If members disagree, the two opinions are shown side by side and the decision is asked from you.
Rules are written, checks are automatic
Guardrail layers
Decisions are made in Claude Code's permission layer (allow · ask · block); the AI can't bypass them. In Codex and Antigravity the same scripts run through that tool's hooks.
On every file write and command
- AI writes / runs
- Secret block
- Destructive command shield
- Package gate
- Structure and scope
- Test separation: stopped
On every commit
- Deterministic gate
- Test source
- Board
- Commit
| Layer | What it does |
|---|---|
| Secret block | Blocks API keys (Anthropic, OpenAI, Stripe, AWS, GitHub, Supabase…) written to code or docs; also scans before a commit |
| Destructive command shield | DROP, TRUNCATE, unconditional DELETE, db reset and pulling prod environment variables onto the machine are blocked; prod deploy, rollback, store submission and migrations are asked |
| Package gate | A package that is installed, or downloaded and run with npx or uvx, is checked against the registry: if it doesn't exist it is blocked; if it is very new, rarely downloaded or looks like a popular package, it is asked |
| Structure guard | A new file outside the map is asked; clutter such as *.bak, *-old.*, copies and temp/ is blocked |
| Config approval | CLAUDE.md, AGENTS.md, .claude/, .codex/, .mcp.json and workflow files don't change without your approval |
| Test separation | The tests are written before the code by a separate agent (test-writer, a different model is recommended), not by whoever writes the code. Nobody but this agent can write to a test file: the main session and the code agent are blocked if they try. A test file changed indirectly by a patch or script also stops at the commit gate. So whoever writes the code can't shape the test to fit their own code |
| Test protection | Deleting or commenting out an assertion, .skip/.only, a loosened assertion, deleting or moving a test file, and narrowing coverage in the test config are asked; so is writing to a test file through the shell |
| Deterministic gate | gate.mjs --run: lint, type check, tests and Semgrep run; the output feeds the board, and a red check counts as REJECT. If the "must not change" behaviors in the spec have no test or the test is red, the gate is red. It is also red if an added line contains a path specific to this machine (the full path of the project folder or the home folder). A new or changed command is first shown to you for approval |
| Commit gate | No commit without a board review and a green gate for the same changes; the task-end approval also counts for the commit, so the same change is not reviewed twice; skipping the review (--skip) is asked every time |
| Edit lock | While /freeze <folder> is on, the AI writes only to that folder; writing outside through the shell is asked, and a symlink can't escape it |
| Scope shield | After /plan-task approval, the plan's file list is saved; writing to an existing file not on the list is asked. Turning the shield on and off is asked too |
| Edit round counter | When the same code file is edited for the 5th and 10th time in a session, a Semgrep and security review reminder appears |
| Dev/prod separation | The local environment and the AI (including read-only MCP) connect only to the dev project; prod secrets stay in the hosting dashboard |
| Security review | security-guidance: a risky-pattern warning while writing (service_role on the client, personal data in logs, innerHTML), and a review by a separate model at the commit |
| When | Where | What it catches |
|---|---|---|
| Push and PR | GitHub Actions | Lint, types, tests, build, Semgrep, duplicate code, folder structure, dependency vulnerabilities, a secret scan across the whole history; a complexity budget on changed files (function: complexity 15 / 80 lines, file: 400 lines); if Supabase is used, an RLS adversarial test against a local Supabase |
| Live | Live monitoring · cloud agents (optional) | A critical-flow and response-time test every 3 hours, an issue and a dashboard warning when it breaks; a fix suggestion for red CI; a weekly maintenance report |
| Every week | Dependabot | Outdated dependencies; majors are planned |
/findings-* · docs/findings/
Findings reports
Scans the project through an expert's eyes and ranks the most important findings, at most 20, with evidence, a 0-100 severity score and a technical fix. Each report gives a health score for its area and is compared with the previous one (new / continuing / worse / resolved).
| Command | Point of view | Example finding |
|---|---|---|
| /findings-tech | Senior architect | The same authorization check is rewritten in 4 places; an unused export; an N+1 query |
| /findings-business | The industry's senior expert (a banker in banking); with web research | No reconciliation flow; the refund rule is undefined; a feature that competitors have as standard is missing |
| /findings-security | Attacker | Someone else's invoice can be read (IDOR); the webhook signature is not verified |
| /findings-ux | User and UX researcher | The empty list screen gives no direction; contrast is 3.1:1 |
| /findings-perf | Performance and FinOps | The dashboard page ships 480 KB of client JS; no max_tokens on the AI call |
| /findings-legal | Compliance expert (not legal advice) | The tax number is missing from the data inventory; the cookie banner loads analytics before consent |
| /findings-all | All the selected ones, in parallel | A combined summary and a shared fix plan |
Severity score = impact (40) + likelihood (25) + spread (20) + urgency (15). Levels: Critical ≥80 · High 60-79 · Medium 40-59 · Low <40. Health = 100 − penalty (critical 15 · high 8 · medium 4 · low 1). At the end of the report are the fix plan, the relevant board member's opinion, and the question of which findings go into the roadmap.
.claude/structure.json · docs/architecture/structure.md
The project structure is protected
The code is organized by feature: everything that belongs to a feature lives under features/<feature>/. If a new file is about to be written outside the structure map, you are asked; clutter files are blocked. Trial work goes to sandbox/, outdated docs to docs/archive/.
.claude/ # commands, agents, hooks, board, findings, structure.json .github/ # CI, Dependabot, live monitoring, cloud agents docs/ product/ prd · roadmap · glossary · launch · feedback · unit-economics · specs/ architecture/ overview · stack · structure design/ design-guide decisions/ log.md + adr-NNNN-*.md quality/ test-plan · metrics · retros · qa/ security/ checklist legal/ privacy-kvkk operations/ release-checklist · deploy-setup · maintenance · accounts · feature-flags · spend-alarms workflow/ progress · decision-protocol · skills · board · usage-limits · cost-log findings/ /findings-* reports archive/ src/features/<feature>/{components,hooks,server,__tests__} # web tests/ sandbox/ # not in git AGENTS.md · CLAUDE.md · README.md · CHANGELOG.md
AGENTS.md holds the shared rules (read by Claude Code, Codex and Antigravity); CLAUDE.md imports it and carries the Claude Code-specific additions. The structure is protected in four places: the hook at write time, CI on every PR, the board's Architect, and /findings-tech. Changing the map is a technical decision; you are asked and it is recorded as an ADR.Where are we, at every moment
Reports and dashboard
At the end of every answer: the status block
── Status ────────────────────── Phase: 1 · Task: G-012 (7/23) · Question mode: open · Limit: 5h 34% weekly 5% Done: signup form + validation, tests green · Board: APPROVE (ux, qa) · Auto decisions: none Next: G-013 password reset · pending decision: email service
Always: the status line
▶ Phase 1 · G-012 · task 7/23 · questions: open · 5h 34% · weekly 5% · context 42%
dashboard.html
- At the top: Now (phase, task, next step), things that need attention (in order of importance), a health badge and summary tiles
- 10 tabs: Overview · Roadmap · Decisions · Board · Findings · Quality · Activity · Product and tech · Operations · Limit and cost
- Product and tech: PRD, MVP and acceptance tests, unit economics, feedback, stack, design, brand pack, promo videos, research notes
- Limit and cost: 5-hour and weekly limit, context, token and API-equivalent cost for the last 30 days (ccusage), limit cost per task
- A Copy button next to the next step and the commands in warnings: you paste the command into the Claude chat
- Updates after every Claude answer and refreshes every 30 seconds while open; it spends no extra tokens
Desktop notification
- When Claude asks a question or waits for approval
- When a job longer than 90 seconds finishes · to turn it off:
KIT_NOTIFY=off
docs/workflow/usage-limits.md
Limit awareness
Before work starts, the 5-hour and weekly limits are read: on the desktop with the get_usage tool, in the terminal and IDE from what Claude Code sends to the status line. The limit is only a reason to warn: work doesn't stop, and continues until you say "stop".
| While working | What happens |
|---|---|
| 90% | A one-line reminder and the reset time; work continues |
| 95% | A "limit is almost gone" warning; where it left off is saved quietly |
| 99% | A "work may be left unfinished" warning; steps are kept small, a WIP commit is suggested |
| If you say "stop" | Stops safely: finishes the step, runs the tests, writes where it left off |
| Level | 5-hour | Weekly | Behavior |
|---|---|---|---|
| green | < 60% | < 70% | Works normally |
| yellow | 60–84% | 70–89% | States the estimated cost, the board is halved |
| red | ≥ 85% | ≥ 90% | States the cost and the remaining share in one line |
Task costs are written to
docs/workflow/cost-log.md; estimates settle on real data over time. At session start only the summary rules and docs/workflow/progress.md are loaded (about 1,700 tokens). If the code map is connected, the code is queried without reading the files. The main session's context is kept small too: independent questions are asked in one round, gate and subagent reports come back short, and /clear is suggested once a task is done and committed..claude/skills · MCP
Capability packs
The core jobs rely on the kit's own skills, not on tools installed from outside; outside tools are turned on only where they make a difference and according to the project type.
The right source
source-research · Context7 · Firecrawl (optional)
- Official docs, law and standards first
- Every claim gets a source, a date and a confidence level (A-D)
- Library docs come up to date from Context7
- The Firecrawl API key stays in your own environment variable
Deployment setup
/release first · deploy-setup.md
- Hosting, environment variables, domain and DNS, backup, rollback rehearsal
- Vercel, Supabase, Railway, EAS; steps with sources and dates
- You enter the secret in the dashboard; it is not written to the chat or to a file
Rules that learn
/fix-bug · /retro · hookify · AGENTS.md
- When the same error class comes a second time, /fix-bug suggests a rule; a warning shows on the dashboard too
- Mechanical rules go to hookify, the rest to AGENTS.md; nothing is written without your approval
- Every rule has a source and a date; /maintain asks about those older than 90 days
- Auto memory is asked at /start, off is recommended
Personal preferences
~/.vibe-kit/preferences.md · prefs.mjs
- When you correct a behavior or say how you want to work, the AI takes a note
- At the end of a task and a session it asks "save this as a preference?"; what you don't approve is not written
- Preferences apply to all your projects and load in every session; they don't go into git
- List:
node .claude/hooks/prefs.mjs --list, remove:--remove <no>
Model per role
docs/workflow/models.md · models.mjs
- Five roles: planning, coding, test writing, review, docs and research
- One question per role at the start of each task (model and effort together), on two screens
- Recommended: plan Opus, code Sonnet, tests Opus, review Sonnet, docs Haiku; all at high effort. Tests use a different model from the code: they don't share the same blind spot
- Test, review and docs work runs in a subagent with the chosen model; the plan runs in the main session
- The roadmap mark, the cost line and the progress labels are written by
progress.mjs; no model call is spent and the format doesn't break - A subagent only when it pays off:
flow.mjslooks at task size, context and limit; a small task stays in the main session, board members are chosen from the changed paths and their number shrinks with the limit; a member writes at most 5 findings
Turkey add-on
--addons tr · docs/legal/turkiye.md
- KVKK transfer abroad: standard contract, 5-business-day notification
- e-Fatura and e-Arşiv thresholds (GİB)
- iyzico and PayTR notification signature code and adversarial test
- İ/ı and Turkish sorting tests; not legal advice
QA and preview in the browser
/qa · preview.mjs · Playwright CLI
- Interface criteria run as tests in a real browser
- The report is written from the test result, a card on the dashboard
- On an interface task /build takes desktop and mobile screenshots
Spec and drift check
docs/product/specs/ · gate.mjs
- Current, expected and must-not-change behavior
- The tests of the "must not change" lines are checked at the gate
- /plan-task for work of 3+ files, /fix-bug writes it for every bug
Logo
logo-design · SVG
- Brand questions, 4-6 concepts with a visual preview
- Readable at 16 px, a one-color version, a dark background
- Favicon, app icons, PNG sizes
Promo video
motion-video · renderAt(t) · Playwright · ffmpeg
- One continuous conversion, a real cursor, 120 BPM
- Closed-form springs (verified with a test)
- A beat map and 4 frames approved first, then MP4
Interface motion and 3D
ui-motion · Motion · Reanimated · GSAP · three.js
- Duration tokens, springs, transform/opacity only
- The reduced-motion preference is mandatory
- 3D: lazy loading, a static fallback, mobile GPU
Review and discovery
rea · Understand-Anything · awesome-design-md
- How a competitor's feature works: only in software you are authorized to examine, with approval first
- A code map for people: suggested by /adopt, /handoff, /release first
Security
security-guidance · claude-security · Trail of Bits
- While writing: a risky-pattern warning
- At the commit: a review by a separate model
- /findings-security: a multi-agent, verified scan
Code intelligence and stack rules
typescript-lsp · pyright-lsp · Vercel · Expo · Supabase
- Type errors after every edit; invented APIs are caught before compiling
- React, React Native, Postgres and Core Web Vitals rules turn on by type
Mobile testing and services
Maestro · Expo MCP · service catalog
- Acceptance tests on a device or simulator
- EAS build, TestFlight crash logs
- GitHub, Stripe, PostHog, Figma: once the service is chosen
Measurement and cost
Playwright CLI · Chrome DevTools MCP · ccusage
- Console, network and screenshots through the CLI; performance traces through MCP
- Tokens and cost per project on the dashboard
Rollback
/rollback · checkpoint.mjs
- A working point is saved while tests are green
- Going back is a new commit; history is not deleted
- Unfinished work is stashed, .env is not touched
In your language
.kit.json → lang
/startand/adoptask the language first: Turkish / English / Other- Questions, answers, documents, the dashboard and the status line come in that language; change it with
/language - Other: the AI translates the hook texts once; saving the translation asks your approval
- Labels and keys in project files (
**Active phase:**,APPROVE) stay English: the tools read them
Narrator mode
output style: narrator
- After every step: what I did, why, how you can see it
- At the end of a task, at most 2 comprehension questions; the answers go on the dashboard
Spend alarm
spend-alarms.md · dashboard
- The provider's cap and a 50%/80% warning
- In code: a per-user quota, a daily budget, automatic shutdown
- /release and /maintain check it
docs/workflow/skills.md
Which skill for which job
| Job | Skill |
|---|---|
| Every code change | ponytail:ponytail |
| Critical flow (auth, payment, data) | mattpocock-skills:tdd |
| Debugging | mattpocock-skills:diagnosing-bugs · /freeze <folder> |
| Questioning the idea and big plans | mattpocock-skills:grilling |
| Glossary, decision record, data model | mattpocock-skills:domain-modeling |
| Module boundaries, architecture | mattpocock-skills:codebase-design |
| Manual setup (DNS, dashboard, store) | mattpocock-skills:wizard |
| Information that can change: version, price, law, competitor | source-research · Context7 |
| Interface by style direction | taste-skill:* |
| Product context, design system, critique/audit/polish | impeccable:impeccable |
| Palette, typeface, tokens | ui-ux-pro-max:* |
| Every text the user sees | humanizer:humanizer |
| Logo, icon, brand pack | logo-design |
| In-app motion | ui-motion |
| Scroll animation (bold direction) | gsap-skills |
| 3D scene (if chosen) | threejs-fundamentals · threejs-performance · threejs-react-three-fiber |
| Promo video | motion-video |
| Status blocks, progress notes | caveman:caveman |
| React/Next performance · React Native | react-best-practices · composition-patterns · react-native-guidelines |
| Database schema, queries, indexes | postgres-best-practices · supabase |
| Expo build, upgrade, store | expo |
| Core Web Vitals, accessibility, SEO | web-quality-skills |
| CLAUDE.md audit · session lessons | claude-md-improver · /revise-claude-md |
| "Don't do this again" → a lasting rule | /hookify |
| Review · audit · debt list | ponytail-review · ponytail-audit · ponytail-debt |
| Deep security scan | /claude-security · Trail of Bits |
Context packs: The skill list is capped at 1% of the context; when it overflows, skills get missed. The core plugins are always on; the design, security, release and video packs come off, and the related command asks to turn them on when needed (
/tools). Adding a new plugin is a technical decision; third-party skills are read before they are installed.Deliberately left out: superpowers, gstack, spec-kit, BMAD, GSD and OpenSpec would replace the kit's question, plan and board flow; their good ideas were worked into the kit's own rules. claude-mem and Serena do the same job as the kit's progress file and code map.
With another tool
Codex and Antigravity
TillerHand was written for Claude Code. The rules, commands and guardrails also work in OpenAI Codex and Google Antigravity. The board runs on a single model; the question UI, the status line and the commit gate are not available in these tools.
npx tillerhand init --tool codex # or antigravity, or claude,codex # add a tool to an existing project /kit-update --tool claude,codex
| Part | Claude Code | Codex | Antigravity |
|---|---|---|---|
| Rules | CLAUDE.md (imports AGENTS.md) | AGENTS.md | AGENTS.md |
| Commands | /start, /build… | Skill: $start or /skills | Skill: /start |
| Guardrails | .claude/settings.json | .codex/hooks.json | .agents/hooks.json |
| "Ask" decision | Approval dialog | Blocked; the AI asks you, and if you approve you do the action yourself | Approval dialog |
| Questions with options | AskUserQuestion | Numbered plain text | ask_question |
| Board and council | Separate agents and models | One model takes the roles in turn | One model |
| Test separation | Enforced by a hook: only test-writer writes to a test file | A written rule (no agent identity) | A written rule (no agent identity) |
| Status line, limit, dashboard refresh, commit gate | Yes | No | No |
The commands have a single source (
.claude/commands/); the copies under .agents/skills/ are generated by init, install and update. Codex runs the project's hooks only when you trust the folder and approve them with /hooks; do this in the first session. On first use, try writing a secret to see the guardrails work..claude/commands
Commands
| Command | What it does |
|---|---|
| /start [idea] | The nine-step wizard: idea, type, install, technology, architecture, board, design, roadmap |
| /adopt | Brings an existing project into the kit: scans it, derives the docs from the code, rewrites AGENTS.md and CLAUDE.md, and builds an alignment roadmap with critical-flow tests and a feature-by-feature move |
| /plan-task [task] | Asks the decision points, produces a plan with the board's opinion, gets approval; writes a spec for work of 3+ files |
| /build [task] | A separate agent (test-writer) writes the acceptance and adversarial tests first, then the code; stops if a new decision comes up; proof (desktop and mobile screenshots on an interface) and the board review |
| /design [scope] | Design decisions with visual previews, and applying them |
| /review-changes [range] | code-reviewer + security-auditor + ponytail-review; asks what to fix with a multi-select |
| /fix-bug [symptom] | Reproduce, prove, bug spec; test-writer writes the red test, then fix, gate; suggests a rule if the same error class repeats |
| /qa [criteria] | Runs the interface criteria in the browser as Playwright tests; the report comes from the test result, a card on the dashboard |
| /freeze <folder> | off | Locks editing to a single folder; the work doesn't spread to other files |
| /rollback [point] | Safely returns to the last working state: unfinished work is stashed, history is not deleted |
| /findings-<type> | tech · business · security · ux · perf · legal · all: a scored findings report |
| /board [setup|convene|council] | Sets up and convenes the expert board; council <question> runs the decision council |
| /ask-mode [on|off] [topic] | Manages the question mode |
| /dashboard | A detailed report and control panel |
| /wrap-up | Progress, decisions, CHANGELOG and dashboard; closes the session |
| /release [first] | Go-live checks; first walks you through hosting, domain, backup and rollback for your provider |
| /maintain [weekly|monthly|quarterly] | Regular maintenance |
| /user-feedback | Sorts user feedback into themes and has you add them to the roadmap |
| /retro | Writes the lessons into the project; kit suggestions go to a branch in the TillerHand repo |
| /research [topic] | Articles, similar projects on GitHub and competing products; a difference table; chosen features go into the PRD |
| /handoff [take] | Hands the project to another person or account, or takes it over; continues from the same place |
| /tools [on|off|measure|commands] | Shows, turns on or turns off context packs; measures the skill load; makes the command list light or full |
| /kit-update | Brings the project to TillerHand's latest version; asks about conflicts; adds a tool with --tool and an add-on with --addons |
| /language [language] | Changes the conversation language (Turkish, English or another language); refreshes the translation of the hook messages and the dashboard |
TillerHand is a project too
Updates and maintenance
Lessons learned in projects flow back into the kit; new versions of the kit reach projects safely.
/retro→
a branch in the TillerHand repo→
approve push / PR→
VERSION + CHANGELOG + tag→
/kit-update
| File type | What happens on update |
|---|---|
| The kit's files: commands, agents, hooks, decision-protocol, skills, security checklist, release-checklist, deploy-setup, maintenance, privacy-kvkk | Replaced with the new one if you didn't change it. If you did, yours stays, the new version arrives as .kit-new, and you are asked how to merge it. |
| The project's files: AGENTS.md, CLAUDE.md, PRD, stack, design, settings.json… | Not touched. The "adapt by hand" items in the CHANGELOG are asked one by one. |
Codex and Antigravity skill copies (.agents/skills/) | Regenerated from the commands on every update. |
| A file newly added to the kit | Added if the project doesn't have it. If you deleted it on purpose before, it is not brought back. |
Evaluation:
node kit/eval/run.mjs runs the same task with and without the kit and scores it with hidden acceptance and adversarial tests. The latest measurement is above, in Results.In every project
Golden rules
- You make the decisions.The AI recommends and gives reasons; the choice is yours. On a topic where you haven't said "don't ask", it doesn't choose on its own.
- Choose design by seeing it.You pick the screen in the preview, not a style described in words.
- Write first, then have it coded.No code without a PRD and an out-of-scope list.
- One task, one session.Split a big task.
- Every working step is a commit.If the AI loses its way, you go back to there.
- Go live on day one.Have the deploy pipeline and CI working from the start.
- Context lives in files.Make
/wrap-upand/cleara habit. - Proof, not "it works".A screenshot, a request/response, test output.
- The two-attempt rule.If the same error isn't solved in two attempts, stop, go back, and re-plan.
- Secrets never go to the client.Everything that goes to the browser and the mobile bundle is public.
- A backup you haven't tested isn't a backup.Try the restore before launch.
- Turn a repeated error into a rule.Write it to the kit with
/retro; if you can, turn it into a hook or a CI step.