@startuml file-lifecycle
!theme plain
title Feature File Lifecycle and Automation Triggers

|Developer|
start
:Create feature request;
:Edit **request.md**;

|Git|
:git add request.md;
:git commit;

|Pre-commit Hook|
:runner.py processes\nrequest.md;

|AI (runner + patcher)|
if (feature.discussion.md exists?) then (no)
  :Generate new\n**feature.discussion.md**:
  - YAML header with promotion rules
  - Summary from request
  - Initial AI comment + vote;
else (yes)
  :Append AI comment to\nexisting discussion;
endif

:Stage feature.discussion.md;

if (feature.discussion.sum.md exists?) then (no)
  :Create from template;
else (yes)
  :Update summary sections;
endif

:Stage feature.discussion.sum.md;

|Git|
:Commit completes with\nauto-generated files;

|Developer|
:Review generated discussion;

if (Make changes?) then (yes)
  :Edit **feature.discussion.md**;
  :Add your comment + VOTE;

  |Git|
  :git add feature.discussion.md;
  :git commit;

  |Pre-commit Hook|
  :workflow.py parses votes;
  :runner.py appends AI response;

  |AI|
  :Read all comments + votes;
  :Calculate promotion status;

  if (READY votes >= threshold?) then (yes)
    :Update status to\n**READY_FOR_IMPLEMENTATION**;

    if (implementation_gate enabled?) then (yes)
      :Generate\n**implementation.discussion.md**;
      :Stage implementation file;
    endif
  endif

  :Append new AI comment\nwith vote analysis;
  :Stage updated discussion;

  |Git|
  :Commit with updates;
endif

|Developer|
if (Status == READY_FOR_IMPLEMENTATION?) then (yes)
  :Begin implementation;
  :Edit **implementation.discussion.md**;
  :Track tasks and progress;

  |Pre-commit Hook|
  :AI adds planning updates;
  :Updates task checklists;

  |Git|
  :Commit implementation progress;
endif

stop

note right
  **Files Auto-Generated:**
  1. feature.discussion.md
  2. feature.discussion.sum.md
  3. implementation.discussion.md (gated)

  **Never Edit These Manually:**
  - .sum.md files (always auto-generated)

  **Edit These Freely:**
  - request.md (your feature spec)
  - *.discussion.md (add your comments)
end note

note right
  **Two Automation Phases:**

  **Phase 1 - Vote Tracking:**
  - Always runs (no AI needed)
  - Parses VOTE: lines
  - Updates .sum.md sections

  **Phase 2 - AI Enhancement:**
  - Requires Claude API/CLI
  - Generates intelligent comments
  - Tracks quorum and status
  - Creates gated files
end note

@enduml