Files

T

Christopher Clendening 96b7ff9766 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.

2026-07-30 13:34:07 -04:00

4.5 KiB

Raw Blame History

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.

4.5 KiB Raw Blame History