lifecycle-events
Use this when an agent begins work (startup), finishes successfully (completion), hits an unrecoverable error (failure), or is retried after a prior failure — and when calculating duration_seconds for
SKILL.mdskills/lifecycle-events/SKILL.md
GitHubLifecycle Events
Provides the exact protocols and JSON schema for logging agent lifecycle events (started, completed, failed, retried) across both Architecture and Detailed Design phases.
When to Activate
- When an agent begins its work (startup protocol)
- When an agent finishes successfully (completion protocol)
- When an agent encounters an unrecoverable error (failure protocol)
- When an agent is retried after a previous failure
- When calculating
duration_secondsfor a lifecycle entry - Used by: ALL 24 agents (architecture-lead, system-decomposer, api-designer, infrastructure-architect, database-architect, pattern-advisor, simulated-cto, simulated-security-architect, simulated-sre, simulated-tech-lead, simulated-product-owner, detailed-design-lead, component-designer, data-model-designer, sdk-designer, interface-designer, algorithm-designer, concurrency-designer, coding-guidelines-generator, guardrail-validator, simulated-senior-developer, simulated-dba, simulated-qa-lead, simulated-security-engineer)
Lifecycle Entry Schema
Per CLAUDE.md rule #1, every lifecycle event uses this exact JSON schema:
{
"run_id": "<from-run-manifest>",
"type": "lifecycle",
"timestamp": "<ISO-8601>",
"agent": "<agent-name>",
"event": "<started|completed|failed|retried>",
"wave": "<1|2|3|4>",
"outputs": ["<list-of-files-written>"],
"duration_seconds": "<elapsed-since-start>",
"error": "<error-description-if-failed>"
}
Field Descriptions
| Field | Type | Required | Description |
|---|---|---|---|
run_id |
string (UUID) | Yes | From run-manifest.json, never self-generated |
type |
string | Yes | Always "lifecycle" for lifecycle entries |
timestamp |
string (ISO-8601) | Yes | UTC with Z suffix, e.g., "2026-03-09T14:30:00Z" |
agent |
string | Yes | Must match agent frontmatter name exactly |
event |
string | Yes | One of: started, completed, failed, retried |
wave |
string | Yes | Wave number: "1", "2", "3", or "4" |
outputs |
string[] | Yes | File paths written; [] for started/failed events |
duration_seconds |
number | Yes | 0 for started events; elapsed seconds for others |
error |
string or null | Yes | null unless event is failed |
Log File Locations
| Phase | File Path |
|---|---|
| Architecture | docs/architecture/decisions/decision-log.jsonl |
| Detailed Design | docs/detailed-design/decisions/decision-log.jsonl |
Lifecycle entries go into the SAME file as decision entries. They are distinguished by "type": "lifecycle" vs "type": "decision".
Startup Protocol
Every agent MUST perform these 3 steps before doing any design work:
Step 1: Read the Run Manifest
Architecture: docs/architecture/state/run-manifest.json
Detailed Design: docs/detailed-design/state/run-manifest.json
Extract the run_id field. If the manifest does not exist or is unreadable, the agent MUST NOT proceed -- escalate to the lead immediately.
Step 2: Note the Start Time
Record the current UTC timestamp. This timestamp is used for:
- The
"timestamp"field in the started lifecycle entry - Calculating
duration_secondsat completion or failure
Step 3: Log the Started Entry
Append to the decision log file:
{
"run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "lifecycle",
"timestamp": "2026-03-09T14:00:00Z",
"agent": "database-architect",
"event": "started",
"wave": "2",
"outputs": [],
"duration_seconds": 0,
"error": null
}
Rules:
outputsis always[]at startup (nothing written yet)duration_secondsis always0at startuperroris alwaysnullat startup- The
startedentry MUST be the first thing appended, before any decision entries
Completion Protocol
When an agent finishes all work successfully, perform these 3 steps in order:
Step 1: Log the Completed Entry
Calculate duration_seconds (see calculation section below) and list all output files:
{
"run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "lifecycle",
"timestamp": "2026-03-09T14:45:00Z",
"agent": "database-architect",
"event": "completed",
"wave": "2",
"outputs": [
"docs/architecture/data/schemas/core-tables.sql",
"docs/architecture/data/schemas/tenant-provisioning.sql",
"docs/architecture/data/schemas/indexes.sql",
"docs/architecture/context/database-architect-summary.md"
],
"duration_seconds": 2700,
"error": null
}
Rules:
outputsMUST list every file the agent wrote, including the context summaryerrorisnullon successful completionduration_secondsis the elapsed time from thestartedentry's timestamp
Step 2: Send Completion Message to Lead
Send a Teammate inbox message to the orchestrator:
- Architecture phase: message
architecture-lead - Detailed Design phase: message
detailed-design-lead
Message format:
database-architect completed. Outputs: core-tables.sql, tenant-provisioning.sql, indexes.sql, database-architect-summary.md. Duration: 2700s. No issues.
Step 3: Notify Downstream Agents (if applicable)
If the agent's output is a critical dependency for other agents, send targeted messages:
[database-architect -> api-designer]: Database-per-tenant isolation design complete. Tenant connection routing uses TenantRouter.GetPool(). See database-architect-summary.md for key constraints.
This step is optional for agents with no known downstream dependencies.
Failure Protocol
Per CLAUDE.md rule #10, when an agent encounters an unrecoverable error, perform these 3 steps:
Step 1: Log the Failed Entry
{
"run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "lifecycle",
"timestamp": "2026-03-09T14:20:00Z",
"agent": "database-architect",
"event": "failed",
"wave": "2",
"outputs": [
"docs/architecture/data/schemas/core-tables.sql"
],
"duration_seconds": 1200,
"error": "Failed to generate tenant provisioning config: requirements document missing tenant isolation requirements for audit_log table"
}
Rules:
errorMUST be a descriptive string (never null, never empty string)outputslists any partial files that were written before failureduration_secondsis calculated from the started timestamp to the failure timestamp
Step 2: Write Partial Output
Write whatever output was completed before the failure. Partial data is always better than no data. Mark incomplete sections:
<!-- Generated: 2026-03-09T14:20:00Z | Run: f47ac10b-... -->
<!-- PARTIAL -- agent failed before completion -->
# Database Architect Summary (PARTIAL)
## Completed
- Core table schemas for primary domain entities
## Not Completed
- Tenant database provisioning for audit_log service
- Index optimization strategy
Step 3: Escalate to Lead
Send an escalation message to the orchestrator:
ESCALATION: database-architect failed -- Failed to generate tenant provisioning config: requirements document missing tenant isolation requirements for audit_log table
The exact format is: ESCALATION: <agent-name> failed -- [reason]
Retry Protocol
When the lead retries a failed agent (max 1 retry per CLAUDE.md rule #10):
Before Retry
The lead archives previous outputs by renaming with .prev suffix:
core-tables.sqlbecomescore-tables.sql.prevdatabase-architect-summary.mdbecomesdatabase-architect-summary.md.prev
On Retry Start
Log a retried lifecycle entry:
{
"run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "lifecycle",
"timestamp": "2026-03-09T14:30:00Z",
"agent": "database-architect",
"event": "retried",
"wave": "2",
"outputs": [],
"duration_seconds": 0,
"error": null
}
Then follow the normal startup protocol (the retried entry replaces started for retries). On completion, log a normal completed entry. The duration_seconds measures from the retry start, not the original start.
Calculating duration_seconds
Duration is the wall-clock elapsed time in whole seconds between the agent's start and its completion or failure.
Method
duration_seconds = completion_timestamp - start_timestamp (in seconds)
Where:
start_timestampis thetimestampfrom the agent'sstarted(orretried) lifecycle entrycompletion_timestampis thetimestampfrom thecompletedorfailedentry
Rules
- Always use whole seconds (integer), not fractional
- For
startedentries, always use0 - For
retriedentries used as a new start, always use0 - On retry, measure from the retry start, not the original start
- If exact measurement is not possible, estimate conservatively
Example Calculation
Started: 2026-03-09T14:00:00Z
Completed: 2026-03-09T14:45:00Z
duration_seconds = 45 minutes * 60 = 2700
Wave Assignments
For the wave field, use the correct value for each agent:
Architecture Phase
| Wave | Agents |
|---|---|
"1" |
system-decomposer |
"2" |
api-designer, infrastructure-architect, database-architect, pattern-advisor |
"3" |
simulated-cto, simulated-security-architect, simulated-sre, simulated-tech-lead, simulated-product-owner |
Detailed Design Phase
| Wave | Agents |
|---|---|
"1" |
component-designer, data-model-designer, sdk-designer |
"2" |
interface-designer, algorithm-designer, concurrency-designer |
"3" |
coding-guidelines-generator |
"4" |
guardrail-validator, simulated-senior-developer, simulated-dba, simulated-qa-lead, simulated-security-engineer |
Examples
GOOD -- Full Lifecycle Sequence
{"run_id":"f47ac10b-...","type":"lifecycle","timestamp":"2026-03-09T14:00:00Z","agent":"api-designer","event":"started","wave":"2","outputs":[],"duration_seconds":0,"error":null}
{"run_id":"f47ac10b-...","type":"lifecycle","timestamp":"2026-03-09T14:50:00Z","agent":"api-designer","event":"completed","wave":"2","outputs":["docs/architecture/api/openapi/order-service.yaml","docs/architecture/api/async/order-events.yaml","docs/architecture/context/api-designer-summary.md"],"duration_seconds":3000,"error":null}
BAD -- Missing Started Entry
{"run_id":"f47ac10b-...","type":"lifecycle","timestamp":"2026-03-09T14:50:00Z","agent":"api-designer","event":"completed","wave":"2","outputs":["docs/architecture/api/openapi/order-service.yaml"],"duration_seconds":3000,"error":null}
Why it is wrong: No started entry was logged. Every agent MUST log started before doing work and completed/failed when done. The lead uses the started entry to track which agents are active.
BAD -- Failed with null error
{"run_id":"f47ac10b-...","type":"lifecycle","timestamp":"2026-03-09T14:20:00Z","agent":"api-designer","event":"failed","wave":"2","outputs":[],"duration_seconds":1200,"error":null}
Why it is wrong: A failed event MUST have a non-null error string describing what went wrong. Silent failures violate CLAUDE.md rule #10 ("No silent failures").
Common Mistakes
Logging started after doing work -- The
startedlifecycle entry must be the very first action, before reading inputs or making decisions. If the agent fails during input reading, the started entry ensures the lead knows the agent attempted to run.Omitting files from the outputs array -- The
completedentry must list ALL files written, including the context summary. Missing files make it impossible for the lead to verify completeness via the manifest.Using null for error on failed events -- Every
failedentry must include a descriptiveerrorstring.nullmeans "no error" which contradicts thefailedevent type. Per CLAUDE.md rule #10, no silent failures are allowed.Incorrect duration_seconds calculation -- Duration measures from the
started(orretried) timestamp to the current event timestamp. Common errors include measuring from session start instead of agent start, or using milliseconds instead of seconds.Wrong wave number -- Each agent has a fixed wave assignment. Using the wrong wave value corrupts the lead's orchestration logic. Check the wave assignment tables above.
Skipping the escalation message on failure -- Logging the
failedlifecycle entry is not enough. The 3-step failure protocol requires: (1) log failed, (2) write partial output, (3) send ESCALATION message to lead. All three steps are mandatory.