Archify Lifecycle Phase Column Rules: Mapping Phases to Visual Columns

Archify lifecycle diagrams reserve columns 0–4 for the main phase rail and columns 0–2 for the event band, aligning terminal outcomes under their originating phases using the N+2 column offset rule to create readable, testable visual flows.

Archify treats lifecycle diagrams as phase maps rather than dense state-transition graphs, using strict column conventions to keep rails, event bands, and terminal outcomes visually aligned. Understanding these Archify lifecycle phase column rules is essential for creating diagrams that render consistently across HTML, SVG, and WebM outputs. The conventions are enforced by the lifecycle renderer and defined in the central skill documentation.

Main Rail and Event Band Allocation

Primary Lifecycle Rail (Columns 0–4)

According to archify/SKILL.md (lines 53–54), columns 0 through 4 are reserved exclusively for the primary lifecycle rail. All ordered phases—such as queued → planning → execution → review → completion—must occupy this horizontal band. This fixed range ensures that the main flow remains visually stable regardless of diagram complexity.

Event and Terminal Band Positioning (Columns 0–2)

Beneath the main rail, columns 0 through 2 host the event and terminal bands. The renderer applies a specific alignment rule: event column N sits directly beneath main rail column N + 2. This offset guarantees that a terminal outcome (success, failure, or canceled) appears in the same visual vertical slot as the phase that produced it, creating a linear narrative flow.

Encoding State Outcomes

Recoverable Failures

A failure that supports retry logic uses type: "failure" combined with a real transition back to an active state. The failure marker renders in the event band at the appropriate column, while the transition arrow points back to the correct phase column on the main rail. This pattern distinguishes transient setbacks from permanent endings without breaking the column alignment.

Terminal Outcomes

Terminal states such as success or canceled occupy the bottom outcome band (columns 0–2) and critically do not continue to further phase columns. Once entered, these states terminate the flow, rendering as final visual elements aligned under their parent phases via the N+2 rule.

JSON Configuration Examples

The following examples demonstrate the column rules in practice, referencing the schema defined in archify/schemas/lifecycle.schema.json.

Basic Lifecycle with Recoverable Failure

{
  "type": "lifecycle",
  "meta": {
    "quality_profile": "showcase"
  },
  "phases": [
    { "step": "01", "label": "Queued" },
    { "step": "02", "label": "Planning" },
    { "step": "03", "label": "Execution" },
    { "step": "04", "label": "Review" },
    { "step": "05", "label": "Completion" }
  ],
  "states": [
    { "id": "queued",   "phase": 0 },
    { "id": "planning", "phase": 1 },
    { "id": "running",  "phase": 2 },
    { "id": "review",   "phase": 3 },
    { "id": "done",     "phase": 4 }
  ],
  "transitions": [
    { "from": "queued",   "to": "planning" },
    { "from": "planning", "to": "running" },
    { "from": "running",  "to": "review" },
    {
      "from": "review",
      "to":   "failed",
      "type": "failure",
      "label": "needs-rework"
    },
    { "from": "failed",   "to": "running" },
    { "from": "review",   "to": "done", "label": "approved" }
  ],
  "events": [
    { "id": "failed",  "column": 2, "label": "Failed" },
    { "id": "done",    "column": 2, "label": "Done" }
  ]
}

Here, the phase numbers 0 through 4 occupy the main rail, while the events use column 2, which aligns under main column 0 + 2 per the alignment rule.

Terminal Outcome Configuration

{
  "events": [
    { "id": "canceled", "column": 1, "label": "Canceled" }
  ],
  "transitions": [
    { "from": "review", "to": "canceled", "label": "reject" }
  ]
}

The canceled event occupies column 1, aligning under main column -1 + 2 = 1, demonstrating how terminal outcomes map to the visual grid.

Implementation and Source Files

The column rules are enforced across several key files in the tt-a1i/archify repository:

• archify/SKILL.md (lines 53–54): Contains the definitive statement of the lifecycle phase-column rule and the N+2 alignment convention.

• archify/renderers/lifecycle/README.md: Defines the renderer-specific contract that implements the phase, column, and event band layout logic.

• archify/references/authoring-contract.md: Establishes the general authoring contract for all diagram types, specifying column ranges for lanes, phases, and groups.

• archify/schemas/lifecycle.schema.json: Provides the JSON schema that validates the structure of phases, states, events, and transitions.

These files collectively ensure that geometry remains stable across renders, making diagrams suitable for automated testing and visual diffs.

Summary

• Archify lifecycle phase column rules reserve columns 0–4 for the main phase rail and columns 0–2 for the event/terminal band.
• The N+2 alignment rule positions event column N directly beneath main rail column N + 2, ensuring visual continuity between phases and outcomes.
• Recoverable failures use type: "failure" with a transition arrow back to the main rail, while terminal outcomes end the flow without further column progression.
• The conventions are enforced by the lifecycle renderer and documented in archify/SKILL.md and related contract files.
• Strict column allocation enables repeatable, testable artifacts across HTML, SVG, and WebM output formats.

Frequently Asked Questions

What columns are reserved for the main lifecycle rail in Archify?

Columns 0 through 4 are reserved for the primary lifecycle rail according to archify/SKILL.md. All ordered phases must occupy this range to ensure consistent rendering and alignment with the event band below.

How does the N+2 alignment rule work for event bands?

Event band columns follow the rule main_column = event_column + 2. This means event column 0 aligns under main column 2, event column 1 under main column 3, and event column 2 under main column 4. This offset ensures terminal outcomes appear directly beneath the phases that generate them.

What distinguishes a recoverable failure from a terminal failure in Archify?

A recoverable failure includes type: "failure" in the transition object and defines a subsequent transition back to an active state on the main rail. A terminal failure (or other terminal state like canceled) has no outgoing transitions and occupies the event band as a final outcome without returning to the main phase flow.

Where are the column rules formally defined in the codebase?

The definitive rules appear in archify/SKILL.md at lines 53–54. Additional implementation details reside in archify/renderers/lifecycle/README.md, while the general authoring contract is documented in archify/references/authoring-contract.md. The JSON schema in archify/schemas/lifecycle.schema.json enforces these structural constraints programmatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}