Skip to content

Project Management Protocol (v2.0)

Philosophy: Documentation is Code

We minimize architectural drift by enforcing a "Plan First" workflow.

The Golden Rule:

"If it isn't in the Work Log (or Spike Log), it doesn't happen."

1. The 3 Tiers of Execution

The agent must assess the request complexity and select the lowest appropriate tier.

🟢 Tier L1: Micro Tasks

  • Scope: Typo fixes, one-line bug patches, minor config tweaks, formatting.
  • Requirement: Commit Message Only.
  • Workflow: Fix -> Test -> Commit.

🟡 Tier L2: Minor Tasks

  • Scope: Component refactors, small features, local tech debt cleanup.
  • Requirement: Append to docs/project_management/daily_log.md.
  • Maintenance: If daily_log.md exceeds ~500 lines, archive it to docs/project_management/archive/YYYY-MM_daily_log.md before appending.

Format:

### [YYYY-MM-DD] {Task Name}
* **Context:** {One sentence on why}
* **Changes:** {List of files/components}
* **Verification:** {Test command or visual check}

🔴 Tier L3: Major Tasks

  • Scope: New features (Epics), Architecture changes, Database schema changes, Complex Logic.
  • Requirement: Dedicated Work Log (docs/project_management/logs/YYYY-MM-DD_feature.md).

Workflow:

  1. Draft: Create the file. Fill "Context" & "Proposed Approach".
  2. Review: User reviews the plan.
  3. Plan Approved: User explicitly approves the "Approach" and "Execution Plan".
  4. Execute: Write code. Update the log's "Execution Notes" with any deviations.
    • Note: The Work Log tracks the Transition (the diff, the reasoning).
  5. Ready for Review: Implementation complete, ready for final verification.
  6. Doc Update: Update docs/architecture/ to reflect the new State (the result).
    • Rule: Update Architecture Docs only during the "Verify & Close" phase.
  7. Complete: Run tests. Mark status [x] in Master Plan.

🧪 Exception: The "Spike"

  • Scope: Research, prototyping, risky libraries.
  • Process: Create experiments/{topic}_spike.ts (or relevant extension). No quality control.
  • Outcome:
    • Success: Reference the specific logic, then move the spike file to experiments/archive/ before starting the L3 task.
    • Failure: Move the file to experiments/archive/ and log the failure in daily_log.md.

2. Best Practices

Context Memory (AI-Only)

At the end of every L3 Log, append a summary block compressed for token efficiency. This allows future agents to quickly ingest the history of this feature without reading the whole thread.

Restore Protocol

If you (the Agent) get lost, confused, or the context window feels fragmented, run the Restore Protocol:

Read docs/project_management/index.md (Master Plan) and the last entry in docs/project_management/daily_log.md to re-orient yourself.

3. Status Management

  • Maintain the Master Plan in docs/project_management/index.md.
  • Update the status of tasks in the Master Plan as they progress.
  • Status Progression: Draft -> Plan Approved -> Ready for Review -> Complete.
  • Use the following status indicators:
    • [ ] Pending
    • [x] Completed
    • ![Status](https://img.shields.io/badge/Status-Complete-green) for visual confirmation in the docs.