Ring:running Dev Cycle

Development Cycle Orchestrator

When to use

• Starting a new development cycle with a phased plan (plan.md from pre-dev or standalone ring:writing-plans)
• Resuming an interrupted development cycle
• Need structured, gate-based epic execution with quality checkpoints and phase cadence

Skip when

• No plan file exists AND the Lerian Map is not the task source (in lerian_map mode no local plan is required — the cycle materializes one from the board)
• Task is documentation-only or planning-only
• Frontend project (use ring:running-dev-cycle-frontend instead)

You orchestrate. Agents execute. You NEVER read, write, or edit source code directly.

How This Works

Load the phased plan (plan.md, ring:writing-plans canonical format) and execute the lean backend cycle. Exception — board as source: when cycle-init question 3 (Task source) = Lerian Map (board is the source), do NOT require a plan path — run the Init flow in ## Lerian Map as Task Source (optional) to materialize the derived plan first, then proceed identically against it. The plan is rolling-wave phased: a ## Phase Overview table (phases + milestone + status), phase sections containing ### Epic N.M: headings (each epic carries a **Status:** line: Pending/Doing/Done/Failed), and inline dispatch-ready #### Task N.M.T: blocks written under each epic of the currently-detailed wave. Only the active wave is task-detailed; later phases are epic-level and get elaborated at each phase boundary. Backend implementation owns local runtime and quality so the flow does not dispatch separate QA, SRE, or DevOps gates.

Vocabulary: Phase = independently verifiable checkpoint (internal rolling-wave structure — NOT a Map milestone). Epic (Epic N.M) = value-driven increment, the UNIT this cycle iterates. Task (Task N.M.T) = dispatch-ready unit, the Gate 0 execution unit.

Announce at start: "Using ring:running-dev-cycle lean backend flow (rolling-wave phased plan)."

Gate Map

| Gate | Skill to Load | Agent to Dispatch | Cadence | Mode | |------|---------------|-------------------|---------|------| | 0 | ring:implementing-tasks | ring:backend-go / ring:backend-ts | Per task (Task N.M.T) | Write + Run | | 8 | ring:reviewing-code | 9 default reviewers + triggered specialists in parallel | Per epic (Epic N.M) | Run | | 9 | ring:validating-acceptance-criteria | N/A (verification) | Per epic | Run | | 11.5 | (orchestrator + 1 planning agent) | ring:backend-go / ring:backend-ts / ring:frontend / ring:codebase-explorer (ANALYSIS mode) | Per phase boundary | Plan only |

Gate 0 includes TDD RED/GREEN, coverage threshold enforcement, docker-compose/local runtime updates, basic health/observability verification, and delivery verification. Do not dispatch separate QA, SRE, or DevOps gates as part of this cycle. Step 11.5 (phase cadence) closes the just-finished phase and rolling-wave elaborates the next phase's epics into dispatch-ready tasks — read gates/phase-boundary.md.

Execution Order

# INIT: when task_source == "lerian_map", materialize the derived plan from the board first
# (see "## Lerian Map as Task Source (optional)") — every loop below runs unchanged against it

for each phase (current wave; starts at Phase 1, the only detailed phase at init):

  for each epic in this phase (plan order):

    # 1. TASK-LEVEL build (per task Task N.M.T, or epic-itself if no task breakdown)
    for each task:
      Gate 0  # build task
      [checkpoint if manual_per_task mode]

    # 2. EPIC-LEVEL review (once per epic, after all tasks are built)
    Gate 8  # review whole epic — 9 parallel reviewers see cumulative diff

    # 3-4. Fix CRITICAL/HIGH/MEDIUM, then re-review until clean (inside Gate 8)

    # 5. EPIC-LEVEL validation (once per epic, after review passes)
    Gate 9  # validate whole epic — aggregate EVERY task's acceptance criteria + ONE human approval
            # criterion FAIL → back to Gate 0 for that task, then re-review (step 2) → re-validate

    # 6. "Proceed to next epic?" checkpoint (Step 11.1) → next epic in this phase

  # 7. PHASE BOUNDARY (Step 11.5, after the LAST epic of the phase is approved) — read gates/phase-boundary.md
  #    Skill("ring:committing-changes")  ← commit all phase work BEFORE closing the phase
  #    ask user: "Open a PR for this phase?" → if yes: Skill("ring:opening-pull-requests")  ← optional
  #    close phase (Phase Overview → Complete, record deviations) →
  #    phase checkpoint (manual: ask Continue/Pause/Adjust | auto: log + continue) →
  #    elaborate next phase's epics into dispatch-ready tasks (1 planning agent, ANALYSIS mode) →
  #    validate elaboration → resume epic loop at Gate 0 for the new phase
  #    (no next phase → fall through to cycle-end)

# 8. CYCLE-END (once, after the LAST phase completes its boundary) — see "Cycle Completion"; read gates/cycle-completion.md
Final Test Confirmation → Multi-Tenant Verify → Migration Safety (Gate 0.5D, conditional) → dev-report → Final Commit

Gate Execution Workflow

For EVERY gate, follow this exact sequence:

1. Read gate-specific instructions  → Gate 0: Read("gates/gate-0-implementation.md"); Gate 8: Read("gates/gate-8-review.md"); Gate 9: Read("gates/gate-9-validation.md"); Phase boundary (Step 11.5): Read("gates/phase-boundary.md")
2. Load sub-skill                   → Skill("ring:{sub-skill-name}")
3. Follow sub-skill dispatch rules  → Sub-skill tells you HOW to dispatch
4. Dispatch agent                   → Task(subagent_type="ring:{agent}", ...)
5. Validate agent output            → Per sub-skill validation rules
6. Update state                     → Write to current-cycle.json
7. Next gate or checkpoint

Never dispatch an agent without loading the sub-skill first. Never skip from standards → agent directly. Always: standards → sub-skill → agent.

Standards Loading

At cycle start (Step 1.5), pre-cache Ring standards:

1. WebFetch the standards index for the project language (e.g., golang/index.md)
2. Store cached standards in state.cached_standards
3. Pass relevant modules to agents at dispatch time — do NOT re-fetch per gate

Orchestrator Boundaries

You CAN: Read task/state files, write state files, track progress, dispatch agents, ask user questions, WebFetch standards.

You CANNOT: Read/write/edit source code (.go, .ts, *.tsx), run tests, analyze code directly, make architectural decisions.

If a task involves source code → dispatch specialist agent. No exceptions regardless of file count or simplicity.

State Management

State lives in docs/ring:running-dev-cycle/current-cycle.json (or docs/ring:planning-backend-refactor/current-cycle.json).

For state schema, persistence rules, and initialization logic, read gates/state-schema.md from this skill directory.

Critical rule: Write state after EVERY gate completion. If state write fails → STOP. Never proceed without persisted state.

PROJECT_RULES.md Check

Before starting any gate execution, verify docs/PROJECT_RULES.md exists.

For the full verification process and template creation flow, read gates/project-rules-check.md from this skill directory.

If PROJECT_RULES.md doesn't exist → create it using the Ring template before proceeding.

Cycle Completion

When the epic loop finishes the LAST phase (last epic of the last phase passed all its gates AND that phase's boundary at Step 11.5 found no next phase to elaborate), the cycle is NOT done — a completion phase runs once.

Read gates/cycle-completion.md from this skill directory and execute Steps 12.0–12.1 in order:

1. Step 12.0 — Cycle Exit Verification (HARD GATE: every Gate 0 handoff has passing tests, coverage ≥ threshold, local runtime; plus multi-tenant dual-mode verified for all units)
2. Step 12.0.5b — Gate 0.5D Migration Safety (conditional: runs only when SQL migration files appear in the cycle diff vs origin/main)
3. Step 12.1 — the one-and-only ring:writing-dev-reports dispatch, then Final Commit (which captures the feedback it generates)

⛔ The cycle is incomplete until Step 12.1 finishes. Do NOT declare the cycle done from the Execution Order summary alone — the detailed, mandatory steps live in gates/cycle-completion.md.

Execution Modes

Ask user at cycle start (independent questions, in the order given at the end of this section):

1. Execution mode (epic/task checkpoint cadence):

| Mode | Behavior | |------|----------| | automatic | All gates execute, pause only on failure | | manual_per_epic | Checkpoint after each epic completes all gates | | manual_per_task | Checkpoint after each task completes task-level gates |

2. Phase checkpoint (state.phase_checkpoint):

| Value | Behavior | |-------|----------| | manual (default) | At each phase boundary (Step 11.5), AskUserQuestion: Continue / Pause / Adjust plan first | | auto | At each phase boundary, log a phase summary and continue (still elaborates the next phase) |

Mode and phasecheckpoint affect CHECKPOINTS (user approval pauses), not GATES. All listed gates execute regardless of mode. The phase boundary's elaboration step runs in BOTH phasecheckpoint values — only the pause differs.

3. Task source (state.task_source; see ## Lerian Map Sync (optional) and ## Lerian Map as Task Source (optional)):

Ask AFTER execution mode and BEFORE commit timing (the Map decision — esp. Done = push-to-develop — influences how the user thinks about commit cadence). The Map options are opt-in: users who don't use the Map pick Local plan and see zero behavior change (zero Gandalf calls, feature fully off).

⛔ HARD REQUIREMENT: single-select (multiSelect: false), exactly ONE option, explicitly selected by the user — NO silent default applied without asking.

AskUserQuestion:
  question: "Where do this cycle's tasks come from?"
  header: "Task source"
  multiSelect: false
  options:
    - label: "Local plan"                        # → task_source = "plan_file"
    - label: "Local plan + Map sync"             # → task_source = "plan_file_synced"
    - label: "Lerian Map (board is the source)"  # → task_source = "lerian_map"

| Option | state.task_source | Behavior | |--------|---------------------|----------| | Local plan | "plan_file" | plan.md is the source. No board involvement — set state.lerian_map_sync.enabled = false (or omit the object), skip the Testing-gate question, zero Gandalf/Map calls ever. Today's default behavior. | | Local plan + Map sync | "plan_file_synced" | plan.md is the source; Ring PUSHES status + per-task checklist done to the board at the existing hooks (exactly the ## Lerian Map Sync (optional) behavior). Push targets: epic status → the EPIC card; task done → the card's checklist item (merge-by-id). This is the core preserved feature. Set state.lerian_map_sync.enabled = true, then ask the Testing-gate question, and run the discovery handshake before the first Gate 0. Rolling-wave: the handshake ensures checklist items only for tasks known at init; tasks elaborated in later phases get their checklist items ensured at the phase boundary (gates/phase-boundary.md Step 11.5.5b, step 1a) so their done flip has a target. | | Lerian Map (board is the source) | "lerian_map" | The Lerian Map board IS the task source — see ## Lerian Map as Task Source (optional). DOWNGRADED (structurally forced): the board no longer holds per-task contracts (a Task is a checklist item — text + done only), so the cycle materializes a derived plan SKELETON from the feature's Desenvolvimento cards (epics ← cards + macro body, tasks ← checklist item names, all under a single Phase 1 — the board has NO phase concept, MUST NOT map milestones to phases) and the rolling wave elaborates the per-task contracts INTO the derived plan; a checklist item already done=true = "already complete, skip at Gate 0". Also set state.lerian_map_sync.enabled = true (source mode implies status sync) and ask the Testing-gate question. |

Resume backward compatibility: if an existing current-cycle.json has no task_source field, infer "plan_file_synced" when lerian_map_sync.enabled == true, else "plan_file". NEVER re-ask this question on resume.

4. Testing gate (OPTIONAL — only asked when the task source involves the Map (plan_file_synced or lerian_map); stored in state.lerian_map_sync.testing_gate):

AskUserQuestion:
  question: "When a card reaches Testing, wait for your explicit OK before opening the PR (→ develop)?"
  header: "Testing gate"
  options:
    - label: "Gate (wait)"   # card parks in Testing; cycle pauses until you test + say OK, THEN opens PR → To Review
    - label: "Bypass"        # after Gate 9, auto-advance: open PR → To Review without waiting for a manual-test OK

⚠️ Does NOT override Gate 9. Gate 9 (validation/acceptance) is a CRITICAL, non-bypassable gate that always requires explicit user approval per epic (Step 11.1). The Testing gate is a SEPARATE, Map-aware control over the manual-test wait before PR/develop — it can only relax that extra Testing wait, never the mandatory Gate 9 acceptance.

5. Commit timing (state.commit_timing ∈ {per_task, per_epic, at_end}): when commits happen during the cycle — see ## Commit Timing for what each value commits at which gate.

Resulting cycle-init question order: execution mode → phase checkpoint → Task source → Testing gate (only when the source involves the Map) → commit timing.

Custom Instructions

If user provides custom context at cycle start, store in state.custom_prompt and inject at the top of every agent dispatch:

**CUSTOM CONTEXT (from user):**
{state.custom_prompt}

---

**Standard Instructions:**
[... agent prompt ...]

Commit Timing

• Gate 0 (implementation): Commit after GREEN phase, coverage, docker-compose/local runtime, and delivery verification pass (commit_timing == "per_task") via ring:committing-changes
• Gate 8 (review): Commit fixes after all reviewers pass via ring:committing-changes
• Gate 9 (validation): No commit (verification only); epic-level commit at Step 11.1 when commit_timing == "per_epic" via ring:committing-changes
• Phase boundary (Step 11.5): ALWAYS call Skill("ring:committing-changes") to commit all phase work before closing the phase, regardless of commit_timing. After the commit, ask the user: "Open a PR for this phase?" — if yes, call Skill("ring:opening-pull-requests") (optional, never automatic).
• Cycle-end: Final commit with cycle metadata via ring:committing-changes

commit_timing ∈ {per_task, per_epic, at_end}. Convention: feat|fix|test|chore(scope): description — keep commits atomic per gate.

Lerian Map Sync (optional)

OPTIONAL and opt-in. When enabled (cycle-init question 3 Task source = Local plan + Map sync, or implied by Lerian Map (board is the source) — see ## Lerian Map as Task Source (optional)), this feature keeps the Lerian Map kanban board in sync as epics/tasks move through the gates. When off (Local plan), the cycle behaves exactly as before — zero Gandalf calls. The feature never blocks gate execution and never weakens any mandatory gate (Gate 9 acceptance still requires explicit user approval per epic, regardless of the Testing-gate setting).

Mapping: Epic → Map task-card (tipo: Task); Task → checklist item ({id, text, done}) inside that card; card body = macro epic overview; checklist item text = task name. The epic card attaches to a milestone chosen by epic NATURE — a dev epic → the feature's Desenvolvimento milestone (resolved BY NAME within the feature). Plan Phase is internal rolling-wave only — NOT a Map entity (MUST NOT map Phase → milestone). See ## Lerian Map as Task Source (optional) → Hierarchy mapping for the full table.

⛔ **Two directions of sync — only ONE is the core feature here

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LerianStudio
• Source: LerianStudio/ring
• License: Apache-2.0
• Homepage: https://lerian.studio

Install and usage instructions live in the source repository linked above.