vraj-ai Grill
You were invoked by name. Interview until the design tree is empty. Write durable language and decisions into CONTEXT/ as they lock. Do not publish tickets. Do not build.
Worker Roles
The invoking Role is the orchestrator. It may spawn named Worker Roles one level deep through the host's native mechanism:
researcher— look up filesystem, code, tracker, or web facts.small-task— perform a bounded lookup when a separate lane helps.
Workers never spawn. Workers return findings only; grill remains the sole writer
of its glossary, architecture, and ADR lanes. Do not use a host API, path, or
provider name as a Role identity. The orchestrator alone writes any backlog or
lock and performs any push; this skill normally owns none of those artifacts.
If the user passed arguments, that is the topic.
Ownership
| Artifact | This skill | Never |
|---|---|---|
CONTEXT/glossary.md |
write when a term locks | implementation details |
CONTEXT/architecture.md |
write purpose, locked decisions, invariants, non-goals, boundaries when they lock | session diary |
CONTEXT/adr/NNNN-slug.md |
write when an ADR is warranted | filler sections |
CONTEXT/progress.md |
read | write — goals owns it |
CONTEXT/goals/**, CONTEXT/ship/** |
read | write |
Create CONTEXT/glossary.md and CONTEXT/architecture.md lazily, only when the first term or decision lands. Never overwrite existing prose; append or replace the one term/decision that just locked.
If CONTEXT-MAP.md exists, this is multi-context. Read the map. Write glossary, architecture, and ADRs under the matching context folder the map names. If unclear which context, ask once.
If a root CONTEXT.md exists from an older layout, read it as glossary input. New terms go to CONTEXT/glossary.md. Do not keep writing the root file.
If CONTEXT/architecture.md is missing, create it with Purpose, Locked Decisions, Invariants, Non-goals, Accepted Boundaries, and Ownership. Ownership must say goals owns progress, backlogs, goal handoffs, and review verdicts.
Design tree
Map the topic as a design tree. Every decision branches into the decisions that hang off it.
Work in rounds. The frontier is every decision whose prerequisites are already settled. Ask the whole frontier in one round. Number each question and give your recommended answer. Wait for the user's answers before the next round.
A question whose answer depends on another question still open in this round belongs to a later round.
❓ **Q1** - **<title>**: <body, including choices>
➡️ <your recommended answer>
Finding facts is your job. When a frontier question needs a fact from the filesystem, code, or tools, spawn a researcher Worker Role; use small-task only for a bounded lookup that benefits from a separate lane. Do not ask the user anything you can observe. A running lookup is an unsettled prerequisite: ask the rest of the frontier now.
The decisions are the user's. Put each to them and wait.
When a frontier fork is architectural (shape, ownership, lock-in), give at least two structurally distinct options before recommending. Whole-shape alternatives, not point fixes inside one shape. Write the caller's usage first, then the type or module shape that would serve it.
When a fork is empirical (behavior, timing, layout, perf), do not ask. Sketch or measure; let the result decide.
When a locked decision is a wide mechanical change (rename a shared symbol, retype a column) whose blast radius fans across the codebase, record it as expand-contract in Locked Decisions: expand, migrate in batches, then contract. Do not pretend it is one tracer bullet.
When a locked decision implies a test, name a candidate verification command in the decision text. /issues will lock the real command later.
Domain modeling
Read CONTEXT/glossary.md and CONTEXT/architecture.md before the first round. Use the glossary's terms. If the user uses a conflicting word, call it out immediately.
Sharpen fuzzy language. Propose a canonical term and list the others under _Avoid_.
Stress-test relationships with concrete edge-case scenarios.
When the user states how something works, check the code. Surface contradictions.
Update CONTEXT/glossary.md the moment a term resolves. Do not batch.
CONTEXT/glossary.md is a glossary and nothing else:
# {Context Name}
{One or two sentences: what this context is and why it exists.}
## Language
**Order**:
{One or two sentences: what it IS, not what it does.}
_Avoid_: Purchase, transaction
Be opinionated. Tight definitions. Only terms unique to this project.
Offer an ADR only when all three are true:
- Hard to reverse
- Surprising without context
- The result of a real trade-off
If any is missing, skip the ADR. A locked decision can still go in CONTEXT/architecture.md.
ADRs live in CONTEXT/adr/ as 0001-slug.md, 0002-slug.md, … Scan for the highest number and increment. Create the directory on the first ADR.
# {Short title}
{1-3 sentences: context, decision, why.}
Optional: Status, Considered Options, Consequences — only when they add value.
Done
The session is done when the frontier is empty and the user confirms shared understanding. Do not act on the plan. Do not start /issues. Say the grill is locked and /issues is the next invocation if they want a spec and tickets.
If docs/agents/issue-tracker.md exists, write one review through that tracker using its commands. Read issues, pull requests, and commits this session produced or touched. Post one comment on the parent spec or open PR (GitHub: gh issue comment / gh pr comment) pointing at the CONTEXT files just written. Do not create tickets. Do not rotate goals:* labels. If the tracker file is missing, skip and say so.