Astra — Agent Architecture

Design Philosophy

Astra is a Mission Control agent that orchestrates a graph of specialized sub-agents. She does not do the work herself — she delegates, validates, and enforces guardrails.

The architecture is designed to be:

• Auditable: every agent action is logged to audit/
• Self-correcting: agents detect failures and route accordingly
• Human-supervised at confidence boundaries: HIGH confidence auto-publishes; MEDIUM/LOW routes to custodian review
• Extensible: new agents can be added without restructuring the pipeline

Agent Graph

┌─────────────────────────────────────────────────────────────────┐
│                        MISSION CONTROL                          │
│                    Orchestrator (Astra)                         │
│         Goal definition · Delegation · Guardrail enforcement    │
└───────────────────┬─────────────────────────────────────────────┘
                    │
        ┌───────────▼───────────┐
        │     INTAKE LAYER      │
        │  Scout + Beat Reporters│
        │  Policy · Tech · DoD  │
        │  Microsoft · Custom   │
        └───────────┬───────────┘
                    │  signals (topic + source + relevance score)
        ┌───────────▼───────────┐
        │    RESEARCH LAYER     │
        │   Analyst (Writer)    │
        │  GPT-5 · Azure AI     │
        │  Foundry · Citations  │
        └───────────┬───────────┘
                    │  draft (.md with frontmatter)
        ┌───────────▼───────────┐
        │  VERIFICATION LAYER   │
        │  Verifier + Editor    │
        │  URL check · Confidence│
        │  scoring · Format QA  │
        └───────────┬───────────┘
                    │  reviewed draft + confidence score
        ┌───────────▼───────────┐
        │    REVIEW GATE        │◄── GitHub Issues (human review)
        │  HIGH → auto-publish  │    JT + Kevin comment "ship it"
        │  MED/LOW → hold       │
        └───────────┬───────────┘
                    │  approved content
        ┌───────────▼───────────┐
        │   PUBLISH LAYER       │
        │  Publisher · Social   │
        │  Site rebuild · Queue │
        │  Twitter/LinkedIn/    │
        │  Mastodon/MS TechComm │
        └───────────┬───────────┘
                    │  published content
        ┌───────────▼───────────┐
        │   ARCHIVE + MONITOR   │
        │  Archivist · Ops Agent│
        │  Freshness · URL check│
        │  Re-verify · Regenerate│
        └───────────────────────┘

Agent Registry

Built

Planned

Pipeline Modes

Autonomous (scheduled, every 6h)

Intake → Analyst → Verifier → Editor → Gate (HIGH only) → Publisher → Social → Archivist

LOW/MEDIUM confidence content is held at the gate and routed to GitHub Issues for custodian review.

Supervised (manual, python run.py pipeline --topic "...")

Same pipeline. --topic flag bypasses intake agents. Useful for targeted research.

Commentary (python run.py commentary <persona_id> [ref_slug] [agency])

Persona agent writes commentary anchored to a published Reference article. Runs through Verifier → Editor → Gate before publication.

Feedback Loops (Planned)

The current pipeline is linear. The target architecture introduces feedback:

1. Research loop: if Analyst draft has too many UNVERIFIED claims, route back to Analyst with additional source context before Verifier
2. Revision loop: if Verifier finds broken sources, Analyst attempts to find replacement citations before confidence is downgraded
3. Re-verification loop: nightly job re-checks all published articles; if citations are stale, queues regeneration

Confidence Levels

Review Interface

Human review happens entirely in GitHub Issues:

• Repo: https://github.com/johnturek/astra-psai
• Label: content-review
• Assigned to: JT (johnturek), Kevin (kevintupper)
• Approval: comment ship it → auto-publish within 30 minutes
• Rejection: comment reject <reason> → issue closed, content flagged

Issue watcher (pipeline/issue_watcher.py) polls every 30 minutes.

Audit Trail

Every agent run writes to audit/:

audit/
  scout_<run_id>.json       — Scout run log
  beat_<run_id>.json        — Beat reporter log
  analyst_<run_id>.json     — Analyst run log
  verifier_<run_id>.json    — Verifier verdict
  editor_<run_id>.json      — Editor check
  pipeline_<run_id>.json    — Full pipeline log
  social_<run_id>.json      — Social post log
  beat_state/               — Per-source content hashes (change detection)
  scout_state/              — Scout source hashes
  review_queue.json         — Content held at review gate
  publish_signal.json       — Latest publish event (for OpenClaw monitor)

Nothing is deleted from audit. Corrections are appended, not overwritten.