Enhance documentation with contributing guidelines, planning docs, and agent policies

2026-05-23 09:39:22 -05:00
parent 252348e592
commit c97a9eb217
8 changed files with 331 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Development Workflow
+
+This project uses Red-Green TDD/BDD and GitHub Flow.
+
+## Red-Green TDD/BDD Cycle
+
+For each behavior increment:
+
+1. Red: describe behavior with a failing specification/test.
+2. Green: implement the smallest change needed to satisfy behavior.
+3. Refactor: improve structure while keeping behavior unchanged.
+
+BDD intent:
+
+- Express behavior in user-meaningful terms.
+- Prefer scenario-oriented acceptance criteria before implementation details.
+- Keep unit and integration tests aligned with documented behavior.
+
+Definition of done for a change:
+
+- Behavior is specified and verified.
+- Relevant tests are passing.
+- Refactoring has preserved behavior.
+- Documentation is updated when contracts or workflows change.
+
+## GitHub Flow Branching Policy
+
+Use short-lived branches from main.
+
+Branch pattern examples:
+
+- feature/<topic>
+- fix/<topic>
+- docs/<topic>
+- chore/<topic>
+
+Branch workflow:
+
+1. Create branch from latest main.
+2. Commit small, reviewable increments.
+3. Open pull request early.
+4. Keep branch current with main.
+5. Merge after review and checks pass.
+6. Delete merged branch.
+
+## Pull Request Expectations
+
+- Clear behavior statement and acceptance criteria.
+- Test evidence for the behavior change.
+- Notes on any architectural or moderation impact.
+- Scope limited to one cohesive change.
+
+## Agent Collaboration Rules
+
+- Agents may support test planning, scenario writing, and review checklists.
+- Agents must not generate executable core project code.
+- For implementation guidance, agents should link primary sources and provide paraphrased walkthroughs.