Home / Engine / Agents and Council Architecture

Affirmology - KAIROS: the Electional & Timing Oracle (Agent Spec v1)

Updated Jun 24, 2026 · Affirmology_Kairos_ElectionalAgent_Spec_v1.md

Affirmology - KAIROS: the Electional & Timing Oracle (Agent Spec v1)

Status: PROPOSAL for Jeff's approval. Not built. Routes through the existing Hermes council pattern.

Why this agent exists

Today the council can read timing through Agastya (Vedic/timing) and Lakshmi (wealth), but there is no dedicated oracle whose ONE job is electional astrology: picking the strongest moment to DO a concrete worldly act (file an LLC, sign a contract, launch a product, send the investor deck, open a round, name a company). Jeff keeps needing this exact thing for business decisions, and he needs it as a repeatable, on-demand capability, not a one-off chat reading. Kairos is named for the Greek god of the opportune moment, the right and critical time, which is precisely what electional astrology finds.

What Kairos does (scope)

1. ELECTIONAL: given an action + a date range + a location/timezone, return ranked candidate date-and-time windows, each with a plain-language WHY tied to (a) the elected chart itself and (b) how it connects to Jeff's (or any circle member's) natal chart.
2. AVOIDANCE: flag the windows to avoid in that range (void-of-course Moon, Mercury/Venus/Mars retrograde and their shadows, eclipse zones, hard aspects to the actor's natal money/career points).
3. CONTEXT: layer the live transit picture so the recommendation is grounded in what is actually happening now, not just a generic textbook rule.
4. HONESTY: if nothing in the range is strong, say so and offer the next clean window beyond it (it already did this for the LLC: June 26 before the retrograde, or Aug 11-13 as the strongest near-term date).

Inputs

• actor (whose chart the act is "born under" - defaults to the requester; supports circle members jeff/sol/colin).
• action (free text: "file LLC", "send investor deck", "open beta", "sign lease").
• window (start + end date; defaults to next 60 days).
• location + timezone for the elected chart (defaults to the actor's current location).
• Live: pulls the actor's cached natal Chart (C19 stored basis) + a fresh timing snapshot.

Outputs

• A ranked list (best first) of 1-5 windows: date, time-of-day band, timezone, a 2-4 sentence mechanism-level WHY, and a one-line risk note.
• A short "avoid" list for the same range.
• A single headline recommendation ("If you can wait, X is strongest; otherwise Y is solid").

Electional rule set Kairos checks (the engine, made explicit)

• Moon: waxing for initiating/building acts; sign and element fit the act (Taurus/earth for formation and money, Gemini/air for communication and platform launches); NOT void-of-course at the chosen time.
• Mercury: direct (and out of shadow) for contracts, filings, signatures, and outbound communication; retrograde windows flagged and explained, not just blocked.
• Benefics: Venus/Jupiter dignified and aspecting the elected Ascendant or Midheaven where possible.
• Personalization (the part generic electional misses): the elected Moon/Ascendant should connect to the actor's OWN natal wealth/career axis. For Jeff that means the elected chart touching his Virgo Sun-Venus in the 8th, his MC/Part of Fortune at the Libra-Scorpio line, his natal Jupiter at 7 Scorpio in the 10th, and his Vertex at 21 Leo in the 7th.
• Malefics: keep Mars/Saturn off the elected Ascendant and off the natal money points.

How it interfaces (build approach, minimal + consistent with the council)

Kairos is a new prompted oracle in the same place the others live, plus one timing helper so it works from real ephemeris data, not vibes: - Add a KAIROS_SYSTEM prompt + role in affirmology-agent/src/affirmology/agents/council.py, in the oracle set Hermes can consult (alongside Agastya/Lakshmi). - Give Kairos a small deterministic timing helper in affirmology-agent/src/affirmology/chart/timing.py: electional_scan(actor_chart, action, window, location) that walks the date range, computes the Moon sign/phase/void status, planetary stations and shadows, and the elected-to-natal aspects, and hands Kairos the candidate days as structured facts. This keeps the astronomy correct and lets Kairos do the interpretation, the same split the rest of the engine uses (math in code, meaning in the oracle). - Expose it to chat via a find_timing tool in affirmology-studio/api/hermes_tools.py (args: actor, action, window) and list it in the Hermes system prompt so Hermes will actually call it. - Corpus grounding: tier-walled A/B retrieval from the transits and western_astrology traditions for the electional reasoning; benchmark-only material stays out.

Acceptance criteria (how we know it works)

1. Ask "best day in the next 30 to file my LLC" and Kairos returns ranked dated windows with WHY + an avoid list, matching a hand-checked ephemeris (Moon sign/phase, Mercury station, void-of-course).
2. It correctly flags Mercury/Venus/Mars retrograde and shadow windows in range.
3. It ties at least one recommendation to the actor's natal money/career points.
4. It degrades gracefully (if timing math fails, it says so and does not invent dates).
5. Demo stays untouched; this is Studio/Hermes-side only; no em dashes; honesty rule enforced.

Build sizing

Small-to-medium. One prompt + one timing helper + one tool + a system-prompt line + tests. No change to the demo, the render pipeline, or chart math correctness. Vendored into affirmology-studio/affirmology-agent/ like the other engine changes.

First job once built

Re-run this exact LLC question on a schedule (or on demand) so the date recommendation always reflects the live sky, and extend it to the investor-send and beta-open decisions.