Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sigilix.ai/llms.txt

Use this file to discover all available pages before exploring further.

guidance and rules.<role> are the simplest part of sigilix.json and the part that moves the most signal. Both are free-form text appended to specialist prompts — Sigilix doesn’t lint them, the models just read them. Quality matters more than length.

​
Two layers, one mental model

LayerWhere it appliesWhen to use
guidanceEvery specialist + the synthesizerRepo-wide truths every reviewer must know
rules.<role>Only that one specialistA rule that only matters to one role
Think of guidance as “what every reviewer should walk in knowing” and rules.<role> as “the focused playbook for this role on this repo.”

​
What good guidance looks like

Good guidance is specific, load-bearing, and short. 
{
  "guidance": "This repo is a TypeScript Cloudflare Worker. State lives in KV (eventually consistent, ~5s replication lag) and Durable Objects (single-key serialized). No filesystem, no setInterval — request lifecycle is bounded. Tests use vitest; jest patterns are out of scope."
}
Every sentence is a real fact a reviewer would otherwise have to discover. The constraints are tight enough to flag concrete mistakes.
A useful rule of thumb: if a smart engineer joining your team would benefit from this paragraph on day one, it belongs in guidance. If they wouldn’t, it doesn’t.

​
Length & structure

Guidance is read on every review, so it counts against the token budget. Targets:
  • Under 150 words is comfortable.
  • 150–400 words is fine for complex stacks; structure it as a bulleted list so the model can attend per-bullet.
  • Over 400 words starts to dilute. Consider moving repo-wide checks into rules.<role> or deterministicChecks instead.
Markdown is allowed and recommended. Bullets, code fences, and bold are all read sensibly: 
{
  "guidance": "**Stack:** Next.js 16 app router, React Server Components by default.\n\n**Hard rules:**\n- No `\"use client\"` in `app/(server-only)/**`\n- All Server Actions in `app/_actions/*.ts`\n- `useEffect` requires a comment explaining why it can't be a server pass\n\n**Patterns to flag:**\n- Imports from `next/router` (replaced by `next/navigation`)\n- Class components in `app/**`"
}

​
Per-role rules

Use rules.<role> when a rule clearly belongs to one specialist’s domain. The role tokens are the internal names:
TokenSpecialistUse for
logicGlyphArchitecture, layering, dependency rules, dead code
securityWardenAuth boundaries, input validation, secret leakage
performancePulseN+1, hot paths, memory, big-O regressions
testsWeaveNaming, semantics, test coverage, branch reachability
{
  "rules": {
    "logic": "Domain code in `src/domain/` may not import from `src/infra/`. The ports/adapters split is enforced manually.",
    "security": "All routes that mutate state must call `requireAuth()` before any side effect. No exceptions for 'internal' routes — internal here means 'authenticated as a service account', not 'no auth needed'.",
    "performance": "Avoid `await` inside `for`-of when the loop body doesn't depend on the previous iteration's result. Use `Promise.all` instead.",
    "tests": "Test files mirror source paths: `src/foo/bar.ts` ↔ `src/foo/bar.test.ts`. Co-located tests are not used."
  }
}

​
Why per-role instead of just guidance?

Two reasons:
  1. Token budget. Repo-wide guidance is read by every specialist. A 200-word security-only rule wastes 200 tokens × 4 specialists × every review. Per-role rules are read once, by the right specialist.
  2. Signal clarity. When you write “All POST routes need CSRF” in guidance, the performance specialist reads it too and now has noise to discount. Put it in rules.security and only Warden sees it.

​
Anti-patterns

These show up regularly and should be moved out:
PatternWhere to put it instead
”Reject lines containing console.log”deterministicChecks (a regex catches this for free)
“Skip dist/** and lockfiles”pathFilters
”Apply this rule only on PRs by user X”Out of scope — Sigilix doesn’t gate on author
”Always approve PRs that only touch comments”Out of scope — Sigilix’s verdict is from the synthesizer, not configurable shortcuts
A 2,000-word style guideExternalize as a linked doc; reference it: "See https://example.com/style for full rules"

​
Iterating

The fast loop:
  1. Drop a sigilix.json with your first-draft guidance into an open PR.
  2. Sigilix re-runs on the next push and reads the new config.
  3. Read the next review — did the prompt hit, miss, or over-flag?
  4. Edit guidance in the same PR. Iterate.
Once happy, merge sigilix.json to your default branch so future PRs inherit it.

Path Filters & Profile

Scope reviews to the files that matter.

Deterministic Checks

Encode hard regex rules that don’t need an LLM.