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:
@@ -0,0 +1,69 @@
|
||||
# DECISIONS.md
|
||||
|
||||
This document defines how Architecture Decision Records (ADRs) work in Local LLC. The actual
|
||||
log of decisions lives in [decisions/](decisions/) — this file is policy, that directory is the
|
||||
record.
|
||||
|
||||
## What is an ADR
|
||||
|
||||
A short document capturing a decision with lasting technical consequence: something that would
|
||||
be expensive or disruptive to reverse, or that future engineers need to understand the reasoning
|
||||
behind rather than just the outcome. An ADR is not a design doc, a PR description, or meeting
|
||||
notes — it's a permanent record of "we decided X, here's why, here's what we considered instead."
|
||||
|
||||
## When to write one
|
||||
|
||||
Write an ADR before implementing, not after, when a decision:
|
||||
|
||||
- Changes how multiple projects or roles interact with shared infrastructure (Gitea, ACT
|
||||
Runner, Plane conventions).
|
||||
- Introduces a new architectural pattern, major dependency, or technology choice a project will
|
||||
build on.
|
||||
- Reverses or significantly amends a previous ADR.
|
||||
- Is flagged `needs-adr` in Plane by the Architect (`PLANE.md`).
|
||||
|
||||
Don't write one for routine implementation choices already covered by `CODING_STANDARDS.md` — an
|
||||
ADR is for decisions that standard doesn't already settle.
|
||||
|
||||
## Who writes and approves them
|
||||
|
||||
- Any engineering role can draft an ADR when they hit a decision point that qualifies.
|
||||
- The Architect approves it before it's considered accepted — this is the Architect's core
|
||||
authority per `ORGANIZATION.md`.
|
||||
- Decisions with company-wide, irreversible impact (per `FOUNDER.md`'s approval table) still
|
||||
require Founder sign-off in addition to Architect approval — the Architect approving a
|
||||
technically sound ADR does not itself clear the Founder's approval gate for decisions that
|
||||
belong there.
|
||||
|
||||
## Process
|
||||
|
||||
```
|
||||
1. Draft using templates/ADR.md
|
||||
2. Open as a PR against decisions/ (numbered, see below)
|
||||
3. Architect reviews — approves, requests changes, or rejects with reasoning
|
||||
4. If it qualifies as Founder-gate territory (FOUNDER.md), get that sign-off too
|
||||
5. Merge — status becomes "Accepted"
|
||||
6. If later reversed, a NEW ADR supersedes it — the old one's status changes to
|
||||
"Superseded by ADR-00XX", it is never deleted or rewritten
|
||||
```
|
||||
|
||||
## Numbering and location
|
||||
|
||||
Files live in `decisions/` as `NNNN-short-title.md`, numbered sequentially starting at `0001`.
|
||||
Numbers are never reused, even for a rejected or later-superseded ADR — the log is append-only.
|
||||
`decisions/README.md` is the index.
|
||||
|
||||
## Format
|
||||
|
||||
Use `templates/ADR.md`. At minimum: Status, Context, Decision, Consequences, Alternatives
|
||||
Considered. An ADR that only states the decision without the alternatives considered isn't
|
||||
useful to the next engineer who wonders "why not X instead" — include enough of the "why not"
|
||||
to make that question unnecessary to re-ask.
|
||||
|
||||
## Relationship to project docs
|
||||
|
||||
A project's `PROJECT.md` (`templates/PROJECT.md`) should link the ADRs that shaped it. An ADR
|
||||
is company-wide by default (in `decisions/`), even when it was motivated by one project — if a
|
||||
decision is genuinely project-specific and has no bearing beyond that project, it can live in
|
||||
the project's own folder instead, but default to the shared log unless there's a clear reason
|
||||
not to.
|
||||
Reference in New Issue
Block a user