feat: Add foundational documentation for security, workflow, and project management
- 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.
This commit is contained in:
Christopher Clendening
@@ -0,0 +1,100 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user