# Local LLC — AI Company OS

This repository is the operating system for Local LLC: a software organization staffed by AI
agents, directed by a human Founder, and coordinated through ordinary engineering tools —
Gitea for source control, Plane for project management, and ACT Runner for CI.

It is not a product codebase. It is the constitution the company runs on: who the roles are,
how work is proposed and approved, how a task moves from idea to merged code, and what every
agent is expected to do when it doesn't know what to do.

## Start here

If you are an AI agent being onboarded into this company, **do not start writing code.**
Follow [ONBOARDING.md](ONBOARDING.md) in order. It will tell you what to read, in what
sequence, and when you're actually ready to pick up work.

If you are the Founder, [FOUNDER.md](FOUNDER.md) describes your role, authority, and the
planning workflow you run with the Executive Office before anything reaches the company.

## Repository map

```
Local-LLC/
├── README.md              you are here
├── COMPANY.md             mission, values, philosophy
├── FOUNDER.md             the human's role and the approval gate
├── ORGANIZATION.md        every role, reporting lines, org chart
├── WORKFLOW.md            the sprint lifecycle end to end
├── ONBOARDING.md          step-by-step read order for new agents
├── EMPLOYEE_HANDBOOK.md   culture and conduct rules for AI employees
├── PLANE.md               how Plane is used (epics, stories, tasks, sprints)
├── GITEA.md               branch/commit/PR/review policy
├── ACT_RUNNER.md          CI policy: triggers, retries, failures
├── CODING_STANDARDS.md    formatting, testing, naming, architecture
├── SECURITY.md            secrets, auth, dependencies, supply chain
├── DECISIONS.md           how architecture decisions get recorded
├── MEMORY.md              the organizational memory system
│
├── decisions/                 the actual ADR log (numbered, append-only)
├── templates/                 ADR, project, sprint, meeting, retro, bug, RFC, roadmap
├── memory/                    company-wide memory: architecture, lessons, terminology
├── projects/                  one folder per real project, following templates/PROJECT.md
└── employees/
    └── project-manager/       full reference role — read this before building the rest
```

Additional `employees/<role>/` folders (architect, backend, frontend, ml, qa, security,
devops, documentation) will be added following the same pattern as `project-manager/`.
`project-manager/` exists first because every other role's work arrives through Plane, which
the Project Manager owns operationally.

## What's real right now

- **Gitea** and **ACT Runner** (Linux and macOS runners) are deployed and reachable.
- **Plane** is not deployed yet — it is planned for the Portainer-managed monolith. `PLANE.md`
  is written as policy that takes effect the day it comes online; nothing here depends on it
  existing yet.
- Everything in this repo is agent-agnostic on purpose. No document names a specific model or
  vendor. Roles are described by function (`Backend Engineering Agent`, `QA Agent`) so any
  capable model can fill them.

## Versioning

This repo is versioned like software, not written once and frozen:

| Version | Milestone |
|---|---|
| **v0.1 — current** | Organization defined: all 14 root policy docs, 8 templates, the decision log, company memory seed files, and the Project Manager role fully built as the reference pattern |
| v0.2 | Remaining employee roles fleshed out (Architect, Backend, Frontend, ML, QA, Security, DevOps, Documentation) |
| v0.3 | Plane deployed and wired to the workflow described in PLANE.md |
| v0.4 | Gitea/ACT Runner placeholders replaced with real instance details |
| v0.5 | First real project run end-to-end through the full sprint lifecycle |
| v1.0 | Operational — the company runs itself within the Founder's approval gate |

Treat every merge to this repo the way you'd treat a merge to any other production system:
reviewed, consistent with what already exists, and never a placeholder pretending to be done.