Add project documentation and update workflow plan
Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
# Branching Strategy
|
||||
|
||||
This repository uses a simple trunk-based model with short-lived branches and
|
||||
`main` as the deploy branch.
|
||||
|
||||
For delivery workflow, see [workflow.md](workflow.md). For PR expectations, see
|
||||
[CONVENTIONS.md](CONVENTIONS.md#git-and-prs).
|
||||
|
||||
## Default Model
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit id: "main"
|
||||
branch docs-change
|
||||
checkout docs-change
|
||||
commit id: "work"
|
||||
commit id: "validate"
|
||||
checkout main
|
||||
merge docs-change
|
||||
commit id: "deploy"
|
||||
```
|
||||
|
||||
## Branch Types
|
||||
|
||||
| Type | Pattern | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Feature | `feature/<short-description>` | New user-facing or system capability. |
|
||||
| Bug fix | `fix/<short-description>` | Defect correction. |
|
||||
| Refactor | `refactor/<short-description>` | Behavior-preserving structural work. |
|
||||
| Documentation | `docs/<short-description>` | Documentation-only changes. |
|
||||
| Chore | `chore/<short-description>` | Tooling or maintenance work. |
|
||||
| AI-assisted local work | `codex/<short-description>` | Short-lived Codex branch when branch creation is useful. |
|
||||
| Hotfix | `hotfix/<short-description>` | Urgent production correction. |
|
||||
|
||||
## Main Branch
|
||||
|
||||
`main` should remain deployable.
|
||||
|
||||
Minimum expectations:
|
||||
|
||||
- required checks pass;
|
||||
- risky migrations and config changes are documented;
|
||||
- production-impacting changes include validation evidence;
|
||||
- direct pushes are limited to maintainers or automation.
|
||||
|
||||
## Feature Branches
|
||||
|
||||
- Keep scope focused.
|
||||
- Rebase or merge from `main` according to reviewer preference.
|
||||
- Delete branches after merge.
|
||||
- Avoid stacking unrelated changes.
|
||||
- Do not include generated build output or handoff artifacts.
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Use short imperative subjects that describe the outcome.
|
||||
|
||||
Examples:
|
||||
|
||||
- `Fix team profile auth recovery`
|
||||
- `Refine admin risk workspace`
|
||||
- `Document engineering workflow`
|
||||
|
||||
Use a longer body when context, migration notes, or validation evidence is
|
||||
important for future archaeology.
|
||||
|
||||
## Hotfixes
|
||||
|
||||
Hotfixes should restore production safely:
|
||||
|
||||
1. Branch from the deployed commit or current `main`.
|
||||
2. Apply the smallest safe fix.
|
||||
3. Validate the failing path.
|
||||
4. Deploy.
|
||||
5. Merge back to `main`.
|
||||
6. Add follow-up cleanup or tests when the hotfix intentionally stayed narrow.
|
||||
Reference in New Issue
Block a user