Christopher Clendening
96b7ff9766
- Create SECURITY.md to outline security policies and practices. - Establish WORKFLOW.md detailing the project lifecycle from planning to retrospective. - Introduce decision log structure in decisions/README.md for tracking architecture decisions. - Document Project Manager role with responsibilities, limitations, and operational workflows. - Implement templates for ADRs, bugs, meetings, projects, retrospectives, RFCs, roadmaps, and sprints. - Set up memory logs for architecture and company-wide lessons learned. - Define terminology for consistent understanding across the organization.
101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
# GITEA.md
|
|
|
|
Gitea is the source of truth for code, documentation, ADRs, and architecture (see `COMPANY.md`).
|
|
Gitea and ACT Runner (Linux and macOS runners) are deployed and reachable today — this document
|
|
governs how every AI employee actually uses them.
|
|
|
|
## Instance
|
|
|
|
- URL: `<GITEA_URL>`
|
|
- Organization: `<ORG_NAME>`
|
|
- Every project lives in its own repository under this organization, matching a folder in
|
|
`projects/` in this repo (the operating-system repo and individual project repos are
|
|
intentionally separate — see `projects/README.md`).
|
|
|
|
## Identity
|
|
|
|
Every AI employee has its own Gitea account, SSH key, and Git identity — never a shared token
|
|
(`COMPANY.md`, `ORGANIZATION.md`). Convention for accounts:
|
|
|
|
```
|
|
<role><n>@<ORG_NAME>.local
|
|
```
|
|
|
|
e.g. `backend1@<ORG_NAME>.local`, `qa1@<ORG_NAME>.local`. The `<n>` suffix exists so the company
|
|
can run more than one instance of a role concurrently (e.g. `backend1`, `backend2`) without
|
|
identity collisions. Git commit author/email must match the employee's own identity — never
|
|
another role's, and never the Founder's.
|
|
|
|
## Branch naming
|
|
|
|
```
|
|
<role>/<task-id>-<short-description>
|
|
```
|
|
|
|
e.g. `backend1/LOC-142-upload-api`, `qa1/LOC-142-upload-api-fix`. The `<task-id>` is the Plane
|
|
task identifier — this is what makes commit-to-task linkage automatic and auditable (see
|
|
`PLANE.md` on why identity + linkage replaces the need for a custom dashboard).
|
|
|
|
- `main` is always deployable. Nothing is pushed to `main` directly, including by the Architect
|
|
or DevOps — everything arrives via reviewed PR.
|
|
- Long-lived feature branches are avoided; if a branch outlives its Task's sprint, that's a
|
|
signal for the Project Manager to check in on it, not to let it drift.
|
|
|
|
## Commit messages
|
|
|
|
```
|
|
<type>(<scope>): <short summary>
|
|
|
|
<body — the "why", not a restatement of the diff>
|
|
|
|
Task: <task-id>
|
|
```
|
|
|
|
`<type>` follows conventional commit types (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`).
|
|
The `Task:` trailer is required — it's what ties the commit back to Plane. A commit without a
|
|
linked task is only acceptable for repo-level housekeeping that isn't tracked work.
|
|
|
|
## Pull requests
|
|
|
|
- Every PR must link its Plane Task in the description.
|
|
- PR description states what changed and why, not just what — the diff already shows what.
|
|
- No PR merges without: (1) at least one review approval from the Architect or a peer engineer
|
|
per `WORKFLOW.md`, (2) a passing ACT Runner run (`ACT_RUNNER.md`), and (3) no unresolved
|
|
`security-hold` label from the Security Engineer.
|
|
- QA verification happens after merge-readiness is otherwise established, per the task lifecycle
|
|
in `WORKFLOW.md` — QA is a gate on the Task closing, not a blocker on the PR merging, unless a
|
|
project's `PROJECT.md` says otherwise.
|
|
- The engineer who opened the PR does not merge their own work — merging is the reviewer's
|
|
action once approval and CI are both green.
|
|
|
|
## Signing
|
|
|
|
Commits should be signed with the employee's own SSH key wherever Gitea's configuration
|
|
supports it. An unsigned commit from an identity that has a registered signing key is treated
|
|
the same as a review red flag — investigate before trusting it.
|
|
|
|
## Reviews
|
|
|
|
Review etiquette is defined in `EMPLOYEE_HANDBOOK.md`. Mechanically:
|
|
|
|
- The Architect reviews anything with architectural impact; routine within-scope PRs may be
|
|
reviewed by a peer engineer in the same discipline.
|
|
- Security-sensitive changes (auth, secrets, dependencies, containers — see `SECURITY.md`)
|
|
always get a Security Engineer review in addition to the standard review.
|
|
- A rejected review returns the PR to the author with specific, actionable comments — see
|
|
`EMPLOYEE_HANDBOOK.md` on what a real review looks like.
|
|
|
|
## Permissions
|
|
|
|
- Engineering roles: write access to their assigned project repositories, no admin/settings
|
|
access.
|
|
- Architect: write + branch protection configuration on repos they're actively designing for.
|
|
- DevOps: admin access scoped to CI/CD configuration (`.gitea/workflows`, ACT Runner settings)
|
|
across all project repos.
|
|
- Security: read access everywhere, write access to security-relevant configuration
|
|
(`SECURITY.md` policy enforcement), and the standing ability to attach a `security-hold`.
|
|
- Project Manager: no code write access required — Plane is their instrument, not Gitea commits.
|
|
- This document (`Local-LLC` repo itself): the Documentation Engineer and Architect have write
|
|
access for policy changes; role-defining or organization-defining changes still route through
|
|
the Founder per `FOUNDER.md`.
|