docs/project_management_rules.md

Project Management Rules

This document defines the required project-management workflow for all contributors in the repository.

File hierarchy

Use the following order of authority when project-management files disagree:

1. ReplicaLab_Comprehensive_Task_Division.md
2. AGENTS.md
3. docs/project_management_rules.md
4. docs/completion.md
5. docs/changes.md
6. docs/<owner>/ folders

Purpose of each file

File	Purpose
ReplicaLab_Comprehensive_Task_Division.md	Source of truth for scope, ownership, dependencies, acceptance criteria, and task status
docs/completion.md	Rollup of completed tasks and active partial tasks
docs/changes.md	Append-only log of deviations from the original plan
docs/<owner>/task_list.md	Owner-local task list and short status summary
docs/<owner>/task_breakdown.md	Owner-local blockers, dependency chain, and execution order
docs/<owner>/notes.md	Working notes, handoff notes, and reminders that are not deviations
docs/<owner>/README.md	Explains the role of the owner folder

Docs folder structure

• Each contributor keeps a folder under docs/.
• Use the actual person name when known.
• If the real name is not yet known, use a role placeholder such as person_a.
• Current owner-folder mapping for this repo:
  • docs/ayush/ = Person B (Ayush)
  • docs/kian/ = Person A
  • docs/max/ = Person C
  • docs/kush/ = Person D
• The minimum expected files per contributor folder are:
  • README.md
  • task_list.md
  • task_breakdown.md
  • notes.md

Start-of-task workflow

Before starting a task:

1. Confirm the task is unblocked in ReplicaLab_Comprehensive_Task_Division.md.
2. Check docs/completion.md for current completed and active partial work.
3. Check docs/changes.md for recent deviations that may affect the task.
4. Check the relevant owner folder in docs/.
5. If the task is shared, identify the remaining sign-off requirement before making changes.

Branch and PR rules

• One task or one tightly related task bundle per branch.
• Use the task id in the branch name when practical.
• Preferred branch name patterns:
  • feature/<task-id>-<short-slug>
  • fix/<task-id>-<short-slug>
  • docs/<task-id>-<short-slug>
  • chore/<task-id>-<short-slug>
• Do not mix unrelated tasks in the same branch or PR.
• Use .github/pull_request_template.md for every PR and .github/ISSUE_TEMPLATE/task.yml for task issues.
• Every PR should include:
  • task id or task ids
  • summary of what changed
  • verification performed
  • docs updated
  • deviations recorded, if any
• If the work is partial, say what remains and who owns the remaining sign-off or implementation.

Task status rules

• Use ⬜ Not started when no meaningful work for the task has landed.
• Use 🟡 Partial when draft work is done but acceptance is not fully met.
• Use ✅ Completed only when the task acceptance criteria are fully satisfied.
• Use ❌ Failed only when the task path is explicitly abandoned or invalidated.

Shared-task sign-off rules

• Shared tasks require all listed owners to sign off before completion.
• The drafting owner must document:
  • what is already done
  • what acceptance item remains
  • who must sign off
• Shared tasks remain 🟡 Partial until that sign-off is recorded.

Executor tracking rules

• If a contributor works on a task assigned to someone else, record that in:
  • ReplicaLab_Comprehensive_Task_Division.md
  • docs/completion.md
  • docs/changes.md
• Assignment does not change automatically just because another person executed the work.
• If ownership should change permanently, that must be logged as a deviation in docs/changes.md.

Deviation logging rules

Append an entry to docs/changes.md whenever any of the following happens:

• a task is executed by someone other than the assigned owner
• a task order changes for dependency or urgency reasons
• a task is re-scoped
• a new process or governance artifact is introduced outside the original plan
• architecture or implementation direction changes from the original source of truth
• a task is marked partial because of a sign-off or dependency issue

docs/changes.md is append-only. Do not rewrite or delete historical entries unless they are factually wrong.

Which file to update when

Situation	Required updates
Task status changes	ReplicaLab_Comprehensive_Task_Division.md, docs/completion.md, owner folder
Task executor differs from assignee	ReplicaLab_Comprehensive_Task_Division.md, docs/completion.md, docs/changes.md
Blocker or next-step change	owner task_breakdown.md, optionally task_list.md
New durable deviation from original plan	docs/changes.md, and any affected source-of-truth file
Contract or interface freeze	source artifact plus backlog and completion tracker

Project memory rule for automated model agents

For automated model agents, the files listed in AGENTS.md are the persistent project memory for the repository.

• Load them into working context at task start.
• Preserve their constraints while working.
• Write back any relevant status, deviation, or planning change before ending work.
• If context is tight, summarize them into working notes, but do not skip them.

Minimal close-out checklist

• The task artifact itself is updated.
• Verification was run or explicitly skipped with reason.
• Tracking docs reflect the current state.
• Deviations are logged if the work changed the original plan.