Senate

AI governance framework — laws, project management, and development lifecycle for constituent projects.

Install

Open Claude Code, Codex, or any AI coding agent in your project directory and paste:

Fetch https://raw.githubusercontent.com/kescott027/senate/main/bootstrap/initiator.md and execute the instructions in it. This is the project directory.

The AI will detect your environment (new repo, existing codebase, or empty directory), download the governance framework, and walk you through setup.

No AI web access? Run curl -sL https://raw.githubusercontent.com/kescott027/senate/main/bootstrap/initiator.md and paste the output to your AI with: "Execute the instructions in this document. This is the project directory." See docs/governance/offline_bootstrap.md for the offline path.

---

How It Works

Laws govern how constituent projects operate. The legislative lifecycle is:

1. A constituent proposes a bill via GitHub Issue
2. The bill is triaged and enters a review period
3. Constituents vote on the bill
4. Passed bills enter a 48-hour executive review window
5. If not vetoed, the law is enacted and added to the codebase

The executive (kescott027) can also enact, repeal, veto, suspend, or amend any law at any time without vote.

Quick Links

• Constitution -- Foundational governance rules, voting thresholds, and executive powers
• Law Index -- All active, amended, and repealed laws
• Membership -- Active constituent projects
• Voting Onboarding Kit -- Fast path to voting readiness
• Voting Readiness Checklist -- Ready/not-ready gate before voting
• Bootstrap Verification Script -- Validates required bootstrap files and law hashes
• Environment Detection Edge Cases -- How bootstrapping handles tricky states
• Offline Bootstrap Guide -- No-network or restricted-network setup
• Bootstrap Transcript Example -- Sample AI exchange and expected outputs
• Onboarding FAQ -- Common bootstrap issues and fixes
• Bootstrap Helper CLI -- Optional download helper (does not replace AI bootstrap)
• Example Constituent Repo -- Reference bootstrapped constituent
• Multilingual Bootstrap Prompts -- Translated prompts for non-English teams
• Sync Protocol -- How constituent projects stay in sync with senate laws
• Executive Overrides -- How executive override power works
• Proposal Intake Workflow -- Triage and review process for bills
• Voting Lifecycle -- Voting, tally, and decision recording
• Contributor Guide -- How to propose and vote

Proposing a Bill

To propose a new law, amendment, or repeal, open a GitHub Issue using the appropriate template:

• New Law -- Propose a new LAW-NNN
• Amendment -- Propose changes to an existing law
• Repeal -- Propose removing an existing law
• Feedback -- Provide feedback on laws or process

See docs/governance/contributor_guide.md for the full proposal and voting guide.

Syncing

Constituent projects sync with the senate at each sprint start. See sync/README.md for the full protocol and templates/sprint-sync-checklist.md for a ready-to-use checklist.

Seed Laws

The senate was founded with 13 seed laws (LAW-000 through LAW-012) covering:

Law	Topic
LAW-000	Operating Principles
LAW-001	Planning Rules
LAW-002	Backlog Format
LAW-003	Engineering Standards
LAW-004	Security Standards
LAW-005	Testing Standards
LAW-006	Release Standards
LAW-007	Observability Standards
LAW-008	Review Cadence
LAW-009	AI Workflows
LAW-010	Continuous Improvement
LAW-011	Blocker Management
LAW-012	Bill Submission Process

Bootstrapping New Projects

The senate provides a complete bootstrapping framework for bringing projects under governance:

• BOOTSTRAP.md -- Template for project owners to define vision, architecture, deliverables, and backlog
• project_management_bootstrapping.md -- AI execution guide for new projects (empty or near-empty repos)
• project_management_bootstrapping_existing.md -- AI execution guide for existing projects (repos with code, history, and in-flight work)
• project_management_skeleton/ -- Clean template files for .project_management/

Which guide to use?

Situation	Guide
Brand new repo, no code yet	project_management_bootstrapping.md
Existing repo with code and history	project_management_bootstrapping_existing.md
Existing .project_management/ needs senate integration	See "Governance Upgrade Path" appendix in the existing project guide

Verify Bootstrap

After bootstrapping, validate required files and law hashes:

python3 scripts/verify_bootstrap.py

Repository Structure

senate/
  CONSTITUTION.md          # Foundational governance document
  MEMBERSHIP.md            # Active constituent register
  README.md                # This file
  laws/
    README.md              # Law index
    active/                # Currently enforceable laws
    repealed/              # Repealed laws (historical record)
    amendments/            # Amendment records
  executive/
    README.md              # Executive override documentation
    overrides/             # Executive override records
  votes/
    README.md              # Voting process documentation
    decisions/             # Decision records
    tallies/               # Vote tally archives
  sync/
    README.md              # Sprint sync protocol
    manifest.json          # Current law manifest with hashes
  templates/               # Templates for constituent projects
  bootstrap/
    initiator.md           # Self-contained install initiator (the ONE file)
    prompts/
      install-prompt.md    # Copy-paste command block for users
  scripts/
    verify_bootstrap.py    # Verify bootstrap files and law hashes
  project_management_skeleton/  # Clean .project_management/ template files
  BOOTSTRAP.md             # Project bootstrap input template
  project_management_bootstrapping.md           # Bootstrap guide (new projects)
  project_management_bootstrapping_existing.md  # Bootstrap guide (existing projects)
  .github/
    ISSUE_TEMPLATE/        # Bill, feedback, and override templates
    workflows/             # GitHub Actions (to be added)