The Software Factory

A schedulable fleet of software-development-lifecycle (SDLC) agents that run locally under your existing developer session auth (antigravity, claude, pi) and in CI on GitHub Actions.

Deterministic scanners enumerate; AI models triage, synthesize, and judge. Findings flow directly into whatever issue tracker your target repository already uses (beads or local reports; public GitHub issues are triaged separately as public input).

---

How It Works

flowchart TD
  subgraph Triggers["Triggers"]
    CLI["CLI (manual)"]
    SCHED["launchd (schedule)"]
    GHA["GitHub Actions (CI)"]
  end

  subgraph Factory["The Software Factory"]
    DISP["factory dispatcher"]
    PRE["Deterministic Pre-pass(scan.py, mine_history.py, etc.)"]
    ENG["Engine Adapter(pi · claude · antigravity)"]
    STORE["Findings Store & State Machine(fingerprint · dedupe · lifecycle)"]
  end

  subgraph Targets["Target Codebase"]
    TGT["Target Repo (/path/to/project)"]
    TM["THREAT_MODEL.md"]
  end

  subgraph Sinks["Pluggable Sinks"]
    BD["Beads (.beads)"]
    GH["GitHub Issues"]
    FILE["Local Delta Reports"]
  end

  CLI --> DISP
  SCHED --> DISP
  GHA --> DISP

  DISP -->|"1. Enumerate"| PRE
  PRE -->|"Inspect"| TGT
  PRE -->|"Read scope"| TM
  PRE -->|"Candidates JSON"| DISP

  DISP -->|"2. Triage & Judge"| ENG
  ENG -->|"Execute SKILL.md"| TGT
  ENG -->|"Structured Findings"| DISP

  DISP -->|"3. Dedupe & State Transition"| STORE
  STORE -->|"Active Beads"| BD
  STORE -->|"Verified public issues (all real severities)"| GH
  STORE -->|"Markdown Delta"| FILE

Core Principles

1. Deterministic-first: Scanners (gitleaks, npm audit, HTMLParser, custom harnesses) enumerate candidate files and metrics. Models never do work a static tool does faster and cheaper.
2. Two-plane architecture: The same portable agent definition (SKILL.md) runs locally with your subscription session auth and in CI with repository API keys.
3. Clean session isolation: Discovery and verification are separate agents. Discovery optimizes for recall; verification runs in a fresh session prompted strictly to disprove the finding.
4. Propose, don’t apply: Agents open PRs, draft wisps/issues, and generate delta reports. Humans retain the merge control point.
5. Noise control & stable fingerprinting: Findings are keyed by sha256(agent:rule_id:normalized_path:normalized_snippet)—deliberately excluding line numbers so refactors don’t trigger duplicate alerts.
6. Public disclosure guard: An explicitly-public target publishes redacted public issues for every real finding, including high/critical; missing visibility fails closed. Human approval is required before creating a linked bead.

---

Quick Start

Prerequisites

• Python 3.9+
• At least one supported AI CLI installed and authenticated: