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,34 @@
|
||||
# ADR-NNNN: <title>
|
||||
|
||||
**Status:** Proposed | Accepted | Superseded by ADR-NNNN | Rejected
|
||||
**Date:** YYYY-MM-DD
|
||||
**Author:** <employee role/identity>
|
||||
**Approved by:** <Architect, + Founder if it clears the FOUNDER.md approval-gate table>
|
||||
|
||||
## Context
|
||||
|
||||
What situation makes this decision necessary? What constraints (technical, organizational,
|
||||
timeline) are in play? A future reader should understand the problem without needing to have
|
||||
been present for the discussion.
|
||||
|
||||
## Decision
|
||||
|
||||
What was decided, stated plainly and specifically enough to act on.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
What else was on the table, and why it wasn't chosen. This is the section that keeps the same
|
||||
question from being re-litigated later without new information.
|
||||
|
||||
- **Alternative A** — why not
|
||||
- **Alternative B** — why not
|
||||
|
||||
## Consequences
|
||||
|
||||
What becomes easier, harder, or different as a result of this decision. Include the honest
|
||||
downsides, not just the benefits — an ADR that only lists upside isn't trustworthy.
|
||||
|
||||
## References
|
||||
|
||||
Links to related ADRs, the Plane epic/story this came from, and any relevant project's
|
||||
`PROJECT.md`.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Bug: <short title>
|
||||
|
||||
**Filed by:** QA Engineer (or whoever found it)
|
||||
**Related Task:** link to Plane
|
||||
**Severity:** Blocker | Major | Minor
|
||||
|
||||
## Expected behavior
|
||||
|
||||
What should have happened, per the Task's acceptance criteria.
|
||||
|
||||
## Actual behavior
|
||||
|
||||
What actually happened. State it plainly — this is not the place to soften a failure
|
||||
(`EMPLOYEE_HANDBOOK.md` — never fabricate or round up results).
|
||||
|
||||
## Reproduction steps
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
A bug filed without reproduction steps isn't actionable — QA reject authority
|
||||
(`ORGANIZATION.md`) comes with the responsibility to make the rejection specific enough to act
|
||||
on (`EMPLOYEE_HANDBOOK.md` review etiquette applies here too).
|
||||
|
||||
## Environment
|
||||
|
||||
Relevant runner (`ACT_RUNNER.md`), branch, commit SHA.
|
||||
|
||||
## Resolution
|
||||
|
||||
Filled in once fixed: linked PR, and confirmation that the regression test described in
|
||||
`CODING_STANDARDS.md` was added.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Meeting — <topic>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Attendees:** <roles/identities present>
|
||||
**Related:** link to the Plane Epic/Story/Task this meeting concerns
|
||||
|
||||
## Purpose
|
||||
|
||||
Why this meeting happened — what decision or alignment it was for.
|
||||
|
||||
## Discussion
|
||||
|
||||
Key points raised, not a full transcript. Capture reasoning behind positions, especially where
|
||||
there was disagreement (`EMPLOYEE_HANDBOOK.md` — disagreement should remain visible in the
|
||||
record, not get smoothed over).
|
||||
|
||||
## Decisions made
|
||||
|
||||
- Decision — owner — any follow-up ADR needed? (`DECISIONS.md`)
|
||||
|
||||
## Action items
|
||||
|
||||
| Action | Owner | Due |
|
||||
|---|---|---|
|
||||
|
||||
Link this file from the relevant Plane Epic/Story so it isn't disconnected from the work it's
|
||||
about (`PLANE.md`).
|
||||
@@ -0,0 +1,39 @@
|
||||
# <Project Name>
|
||||
|
||||
**Status:** Planning | Active | Paused | Complete
|
||||
**Epic:** link to the Plane Epic this project executes
|
||||
**Gitea repo:** `<ORG_NAME>/<repo-name>`
|
||||
|
||||
## Summary
|
||||
|
||||
One paragraph: what this project is and why it exists. Should trace back to the Founder-approved
|
||||
plan that created its Epic (`FOUNDER.md`).
|
||||
|
||||
## Scope
|
||||
|
||||
What's in. What's explicitly out — scope boundaries matter as much as the goal itself, since
|
||||
scope creep inside an approved Epic is one of the things `WORKFLOW.md` asks engineers and the
|
||||
Architect to actively watch for.
|
||||
|
||||
## Architecture
|
||||
|
||||
High-level design. Link out to relevant ADRs (`decisions/`) rather than restating their
|
||||
reasoning here — this section should read as a map, not a duplicate of the decision log.
|
||||
|
||||
## Roles involved
|
||||
|
||||
Which engineering disciplines this project needs (not every project needs all of them) and
|
||||
anything project-specific about how they collaborate beyond what `ORGANIZATION.md` already
|
||||
covers.
|
||||
|
||||
## CI / deployment notes
|
||||
|
||||
Anything about this project's ACT Runner configuration or deployment pipeline that goes beyond
|
||||
the default in `ACT_RUNNER.md`.
|
||||
|
||||
## Status log
|
||||
|
||||
Brief dated entries at major milestones — not a duplicate of Plane's burndown, just enough for
|
||||
someone reading this file cold to understand the project's trajectory.
|
||||
|
||||
- YYYY-MM-DD — <milestone>
|
||||
@@ -0,0 +1,29 @@
|
||||
# Retrospective — Sprint <N>, <Project Name>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Facilitated by:** Project Manager
|
||||
|
||||
## What went well
|
||||
|
||||
Concrete, not generic — specific enough that repeating it is actually actionable.
|
||||
|
||||
## What didn't go well
|
||||
|
||||
Same standard. Name the actual friction, not a softened version of it.
|
||||
|
||||
## Root causes
|
||||
|
||||
For anything in "what didn't go well" — why did it actually happen, not just what happened. This
|
||||
is the section that turns a retrospective from a vent into something useful.
|
||||
|
||||
## Changes for next sprint
|
||||
|
||||
Concrete, ownable changes — not "be more careful."
|
||||
|
||||
- Change — owner
|
||||
|
||||
## Memory update
|
||||
|
||||
This is the section that matters most: what from this retro gets written into
|
||||
`memory/lessons-learned.md`? A retrospective that produces no memory update didn't do its job
|
||||
(`WORKFLOW.md`). List the exact entry (or entries) added, so it's traceable.
|
||||
@@ -0,0 +1,32 @@
|
||||
# RFC: <title>
|
||||
|
||||
**Author:** <role/identity>
|
||||
**Status:** Draft | Under Review | Accepted (→ becomes an ADR) | Withdrawn
|
||||
**Date:** YYYY-MM-DD
|
||||
|
||||
An RFC is for a proposal that isn't a decision yet — it's the space to float and pressure-test
|
||||
an idea across roles before it's settled enough to become an ADR (`DECISIONS.md`). Not every
|
||||
decision needs an RFC first; use one when the idea is significant enough to benefit from
|
||||
review before it's committed to, and not yet clearly right.
|
||||
|
||||
## Problem
|
||||
|
||||
What isn't working, or what opportunity this addresses.
|
||||
|
||||
## Proposal
|
||||
|
||||
The actual idea, described concretely enough that a reviewer can find holes in it.
|
||||
|
||||
## Open questions
|
||||
|
||||
What the author genuinely doesn't know yet — an RFC with no open questions probably didn't need
|
||||
to be an RFC; it could have just been an ADR.
|
||||
|
||||
## Feedback
|
||||
|
||||
Reviewers add comments here (or link to the PR thread where the RFC was discussed). Capture
|
||||
disagreement, not just consensus (`EMPLOYEE_HANDBOOK.md`).
|
||||
|
||||
## Outcome
|
||||
|
||||
If accepted: link to the resulting ADR. If withdrawn: why, briefly — that's worth keeping too.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Roadmap — <Project Name or Company>
|
||||
|
||||
**Owner:** CEO (company-level) or Project Manager (project-level)
|
||||
**Last updated:** YYYY-MM-DD
|
||||
|
||||
A roadmap here is a snapshot for human/agent readability — Plane's Epics and milestones
|
||||
(`PLANE.md`) remain the actual source of truth for priority and sequencing. If this file and
|
||||
Plane disagree, Plane is right and this file is stale; update it.
|
||||
|
||||
## Now
|
||||
|
||||
Epics/Stories actively in progress this cycle. Link to Plane.
|
||||
|
||||
## Next
|
||||
|
||||
Approved (cleared the `FOUNDER.md` gate) but not yet started.
|
||||
|
||||
## Later
|
||||
|
||||
Directionally likely but not yet through the approval gate — clearly marked as such so no one
|
||||
mistakes "later" for "approved."
|
||||
|
||||
## Explicitly out of scope
|
||||
|
||||
What this roadmap deliberately excludes, and why — as useful as what's in scope, especially for
|
||||
preventing scope creep an engineer might otherwise assume is implied.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Sprint <N> — <Project Name>
|
||||
|
||||
**Start:** YYYY-MM-DD
|
||||
**End:** YYYY-MM-DD
|
||||
**Opened by:** Project Manager
|
||||
|
||||
## Goal
|
||||
|
||||
One or two sentences: what this sprint is meant to accomplish, in terms of the Stories it pulls
|
||||
in — not a restatement of the whole Epic.
|
||||
|
||||
## Stories in scope
|
||||
|
||||
- [ ] Story — link to Plane
|
||||
- [ ] Story — link to Plane
|
||||
|
||||
Pulled from Stories the CEO has already prioritized (`PLANE.md`) — a sprint should not include
|
||||
un-prioritized backlog items.
|
||||
|
||||
## Assignments
|
||||
|
||||
| Task | Role | Assignee |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
## Blockers watch
|
||||
|
||||
Anything the Project Manager is actively tracking mid-sprint. Update as they arise/resolve —
|
||||
this section should reflect current state, not accumulate history (that belongs in the
|
||||
retrospective).
|
||||
|
||||
## Close-out
|
||||
|
||||
**Closed:** YYYY-MM-DD
|
||||
**Completed / carried over:** summary of what finished vs. moved to the next sprint, and why.
|
||||
**Velocity note:** link to Plane's burndown view rather than re-deriving numbers here.
|
||||
|
||||
Followed by a retrospective — see `templates/RETROSPECTIVE.md`.
|
||||
Reference in New Issue
Block a user