#Eko Rules Index

Central index for all rules, conventions, and standards in the Eko codebase.

Quick Start: New to Eko? Start with CLAUDE.md for the essential invariants and commands.

---

#Rule Categories

Category	Source	Enforcement	Owner
Eko Invariants	CLAUDE.md	Advisory	architect-steward
Eko GTD	docs/rules/eko-gtd.md	Advisory	architect-steward
Doc Conventions	docs/CONVENTIONS.md	CI (docs:lint)	architect-steward
Agent Boundaries	.claude/agents/*.md	CI (agents:routing-check)	architect-steward
Code Style	biome.json	CI (lint)	ci-quality-gatekeeper
Error Handling	docs/rules/error-handling.md	CI (check-error-handling)	observability-analyst
Testing	docs/rules/testing.md	Advisory	ci-quality-gatekeeper
Security	docs/rules/security.md	CI + Pre-commit	security-reviewer
Dependencies	docs/rules/dependencies.md	Advisory	ci-quality-gatekeeper
Styling	docs/rules/styling.md	Advisory	card-ux-designer
Challenge Content	docs/rules/challenge-content.md	Generation + upload validation	fact-engineer
Changelog	docs/rules/changelog.md	Pre-commit (advisory)	docs-librarian

---

#Eko Invariants

Source: CLAUDE.md Enforcement: Advisory (architect-steward reviews) Owner: architect-steward

These are the non-negotiable constraints that define Eko's product boundary:

ID	Invariant	Description
INV-001	Fact-first	Facts are the atomic unit; everything flows from structured, schema-validated facts
INV-002	Verification before publication	No fact reaches the public feed without at least one validation tier pass
INV-003	Source attribution	Every fact traces back to source articles and validation evidence
INV-004	Schema conformance	Fact output must validate against fact_record_schemas.fact_keys
INV-005	Cost-bounded AI	All AI calls have model routing, budget caps, and cost tracking
INV-006	Public feed / gated detail	Feed is public; full card detail and interactions require Free/Eko+ subscription
INV-007	Topic balance	Daily quotas per topic category prevent content monoculture
INV-008	Challenge answer isolation	Challenge URLs, shared links, and metadata must never reveal answer content

Tradeoff priority: correctness, auditability, safety, cost control

---

#Eko GTD

Source: docs/rules/eko-gtd.md Enforcement: Advisory Owner: architect-steward

Eko GTD is a structured planning and execution methodology that scales from minute tasks to major builds.

#Complexity Tiers

Tier	Duration	Tracking
XS Minute	< 30 min	TODO.md (flat)
QS Quick	30 min - 2h	TODO.md (flat)
S Small	2-4 hours	TODO.md (mini)
M Medium	4-6 hours	TODO.md (mini+)
L Large	6-10 hours	TODO.md (full)
XL Major	10+ hours	TODO.md (full)

#Auto-Detection

Claude assesses task complexity automatically:

ID	Rule	Description
GTD-001	Challenge-Based	Requirements become numbered PASS/FAIL challenges
GTD-002	State Tracking	Frontmatter enables session-resumable work
GTD-003	Wave Organization	Challenges grouped by dependency order
GTD-004	Quality Tiers	Functional + quality challenges for A+ grading
GTD-005	Agent Ownership	Every challenge has a single owner agent
GTD-006	Scaled Structure	Full docs for L/XL, mini for S/M, flat TODO for XS/QS
GTD-007	Auto-Detection	Complexity assessed before routing
GTD-009	Universal Tracking	Every tier gets a TODO.md for session resumability

Light tracking (XS/QS): Single-file, no schema/API changes, < 2 hours — flat TODO.md Full GTD (S+): Multi-file, schema changes, cross-package, unclear requirements — challenges + waves

Invocation: Use Eko GTD:<Domain> to <task> Domains: Software, Marketing, Content, Video, Ads, Research, Business

---

#Documentation Conventions

Source: docs/CONVENTIONS.md Enforcement: CI (bun run docs:lint) Owner: architect-steward

ID	Rule	Description
DOC-001	Required front-matter	All docs need: title, status, version, last_updated, scope
DOC-002	Status lifecycle	draft → stable → deprecated
DOC-003	File naming	kebab-case.md only
DOC-004	Cross-links	Relative paths with .md extension
DOC-005	CONTRACT docs	Architecture/product/spec/policy require: related_code, changelog

---

#Agent Boundaries

Source: .claude/agents/README.md Enforcement: CI (bun run agents:routing-check) Owner: architect-steward

ID	Rule	Description
AGT-001	Single ownership	Each file has exactly one agent owner
AGT-002	No overlaps	owned_paths must not overlap between agents
AGT-003	Escalation protocol	Multi-agent work follows handoff sequence
AGT-004	Non-goals	Agents explicitly define what they do NOT do

See Agent Quick Lookup for file→agent mapping.

---

#Code Style

Source: biome.json Enforcement: CI (bun run lint) + Pre-commit (lint-staged) Owner: ci-quality-gatekeeper

ID	Rule	Enforcement
STY-001	No unused imports	Error
STY-002	No unused variables	Error
STY-003	No explicit any	Warning
STY-004	Single quotes	Auto-fix
STY-005	Semicolons as needed	Auto-fix
STY-006	2-space indent	Auto-fix
STY-007	100 char line width	Auto-fix

---

#Error Handling

Source: docs/rules/error-handling.md Enforcement: CI (bun run check-error-handling) Owner: observability-analyst

ID	Rule	Description
EH-001	Structured errors	Errors have code, message, context
EH-002	Never swallow	Catch blocks must log, rethrow, or return Result
EH-003	Worker boundaries	Workers wrap processing in try/catch
EH-004	API responses	HTTP errors return { error, code } JSON

---

#Testing

Source: docs/rules/testing.md Enforcement: Advisory Owner: ci-quality-gatekeeper

ID	Rule	Description
TST-001	Colocation	Test files beside source: foo.test.ts
TST-002	Naming	describe('Component') / it('should...')
TST-003	Fixtures	Store in __fixtures__/
TST-004	Mocking	Mock external services, not internal logic
TST-005	Coverage	packages/shared ≥80%, workers ≥60%, apps ≥40%

---

#Security

Source: docs/rules/security.md Enforcement: CI + Pre-commit (gitleaks) Owner: security-reviewer

ID	Rule	Description
SEC-001	URL validation	SSRF prevention via verifyAndNormalizeUrl()
SEC-002	Service role	SERVICE_ROLE_KEY only in workers
SEC-003	Secrets in logs	Never log API keys, tokens, credentials
SEC-004	RLS testing	Tables with RLS must have security tests
SEC-005	Input validation	All user input validated with Zod
SEC-006	Challenge URL answer leak	Challenge URLs must not reveal answer content

---

#Dependencies

Source: docs/rules/dependencies.md Enforcement: Advisory Owner: ci-quality-gatekeeper

ID	Rule	Description
DEP-001	Package location	Shared deps in root, specific in package
DEP-002	Version pinning	Caret for most, exact for critical
DEP-003	Approval needed	Review for >50KB, native, <1k downloads
DEP-004	Workspace protocol	Internal refs use workspace:*

---

#Styling

Source: docs/rules/styling.md Enforcement: Advisory Owner: card-ux-designer

ID	Rule	Description
STY-101	Inline padding overrides	Use inline style for padding when overriding base input styles
STY-102	Prefer InputGroup	Use InputGroup pattern for inputs with icons/addons
STY-103	CSS layer awareness	Tailwind v4 utilities are in @layer utilities, unlayered CSS wins

Key Gotcha: In Tailwind v4, utility classes like pl-11 are in @layer utilities. Our components.css is unlayered, so base styles override utilities. Use inline style props when you need to override base padding.

---

#Challenge Content

Source: docs/rules/challenge-content.md Enforcement: Generation + upload validation (validateChallengeContent()) Owner: fact-engineer

ID	Rule	Description
CC-001	Minimum style coverage	Every published fact needs challenge content for >= 3 styles
CC-002	Five-field structure	All styles require setup_text, challenge_text, reveal_correct, reveal_wrong, correct_answer
CQ-001–CQ-008	Content quality	Field length, voice, banned patterns, plausibility checks
CQ-009–CQ-013	Style data validation	Per-style structure requirements for fill_the_gap, direct_question, statement_blank, reverse_lookup, free_text

See challenge-content.md for full rule details and examples.

---

#Changelog

Source: docs/rules/changelog.md Enforcement: Pre-commit (advisory) + CI (changelog:check) Owner: docs-librarian

ID	Rule	Description
CHG-001	Update on commit	Commits changing functionality must update the current month's changelog (docs/changelog/MM-YYYY.md)
CHG-002	Category matching	Entries must use correct category (Features, Bug Fixes, etc.)
CHG-003	Scope prefix	Entries should include scope in bold (e.g., Admin Dashboard:)
CHG-004	Date grouping	New entries go under today's date section
CHG-005	Imperative mood	Use imperative verbs (Add, Fix, Update, Remove, Refactor)

What requires entry: Features, bug fixes, breaking changes, security fixes, performance improvements, user-visible refactoring.

What doesn't: Internal refactoring, test-only changes, dev tooling, comment fixes.

---

#Enforcement Levels

Level	Meaning	Failure Behavior
CI	Automated check in CI pipeline	Blocks merge
Pre-commit	Checked before commit	Blocks commit
Advisory	Documented expectation	No automated block

---

#Validation Commands

# Run all rules validation
bun run rules:check

# Individual checks
bun run docs:lint              # Documentation conventions
bun run agents:routing-check   # Agent boundaries
bun run lint                   # Code style
bun run typecheck              # Type safety
bun run check-error-handling   # Error handling patterns
bun run check-invariants       # Invariant violation detection (advisory)

---

#Adding New Rules

1. Determine rule category and owner agent
2. Add rule to appropriate docs/rules/*.md file
3. Assign rule ID following pattern: {CATEGORY}-{NUMBER}
4. Update this index table
5. If enforcement needed, add to CI or pre-commit hooks
6. Run bun run rules:check to validate

---

#Rules Ownership by Agent

Agent	Owned Rule Categories
architect-steward	Eko Invariants, Doc Conventions, Agent Boundaries
ci-quality-gatekeeper	Code Style, Testing, Dependencies
docs-librarian	Changelog
observability-analyst	Error Handling
security-reviewer	Security
card-ux-designer	Styling
fact-engineer	Challenge Content

See Agent System for full agent documentation.