Document Lifecycle Skill

Manages document state transitions, unified numbering, and automated closure across all agent-output directories.

Core Principle

Every work chain shares a single ID. When Analyst creates analysis 080, the downstream plan, implementation, QA, UAT, and critique all use ID 080. This enables human traceability across the entire lifecycle.

Documents in terminal status belong in closed/ subfolders. Active work stays visible; completed work is archived but accessible.

Terminal Statuses

These statuses trigger document closure (move to closed/ ):

Status Meaning Closed By

Committed

Changes committed to git (awaiting release) DevOps

Released

Successfully pushed/published DevOps

Abandoned

Explicitly dropped, will not proceed User (manual)

Deferred

Postponed indefinitely User (manual)

Superseded

Replaced by a newer document User (manual)

Resolved

All findings addressed (critiques only) Critic

Unified Numbering Protocol

The .next-id File

Location: agent-output/.next-id

Contents: Single integer (e.g., 081 )

Rules:

• Only originating agents (Analyst, Planner when no analysis) read and increment

• Downstream agents inherit the ID from their source document

• Never skip numbers; always use the next available

Document Header Format

Every document in agent-output/ MUST include:

ID: 080 # Global sequence number Origin: 080 # Chain origin (same as ID for originating docs) UUID: a3f7c2b1 # 8-char random hex for collision-proofing Status: Active # Current lifecycle state

ID Assignment Rules

Scenario Action

Analyst starts new investigation Read .next-id , increment, use as ID, write back

Planner creates plan from analysis Inherit ID/Origin from analysis doc

Planner creates plan from user request (no analysis) Read .next-id , increment, use as ID, write back

Implementer/QA/UAT/Critic work on plan Inherit ID/Origin from plan doc

Retrospective reviews plan Inherit ID/Origin from plan doc

Close Procedure

When a document reaches terminal status:

• Update Status field to the terminal status

• Add changelog entry: | YYYY-MM-DD | [Agent] | Document closed | Status: [status] |

• Create closed folder if needed: mkdir -p agent-output/<domain>/closed/

• Move file: mv agent-output/<domain>/NNN-name.md agent-output/<domain>/closed/

• Log action: "Closed document NNN-name.md (Status: [status])"

Cross-Reference Handling

When referencing a closed document from another document, use relative paths:

• From active doc: ../closed/080-feature.md

• From closed doc to closed doc: ./080-feature.md (same folder)

Orphan Detection

Agent Self-Check (Every Session Start)

Before starting work, each agent MUST:

• Scan their exclusive domain (e.g., agent-output/qa/ ) excluding closed/

• Identify any document with terminal Status

• Move orphaned documents to closed/

• Log: "Found orphaned document [name] with Status [status], moved to closed/"

Roadmap Periodic Sweep

Roadmap agent performs comprehensive sweep when reviewing roadmap:

• Scan ALL agent-output/*/ directories (excluding closed/ )

• Flag documents with terminal Status not in closed/

• Report to user

• Move to respective closed/ folders

Agent Responsibilities

Agent Role Closure Trigger

Analyst Originate IDs Planner closes when plan created

Planner Originate or inherit DevOps closes after commit

Implementer Inherit DevOps closes after commit

QA Inherit DevOps closes after commit

UAT Inherit DevOps closes after commit

Critic Inherit Self-closes when findings resolved

DevOps N/A Self-closes after release

Retrospective Inherit PI closes after processing

PI N/A Self-closes own analysis

Architect N/A Evergreen docs, no closure

Roadmap N/A Orphan sweep responsibility

Security Inherit Self-check only

Quick Reference

Creating a New Document (Originating)

Read current ID

NEXT_ID=$(cat agent-output/.next-id)

Increment for next use

echo $((NEXT_ID + 1)) > agent-output/.next-id

Use $NEXT_ID as your document ID

Closing a Document

Update Status in document header to terminal status

Add changelog entry

mkdir -p agent-output/<domain>/closed/ mv agent-output/<domain>/NNN-name.md agent-output/<domain>/closed/

Self-Check Pattern

Before starting work:

1. List agent-output/<my-domain>/*.md (excluding closed/)
2. For each file, check Status field
3. If Status in [Committed, Released, Abandoned, Deferred, Superseded, Resolved]: → Move to closed/