القائمة
Orchestrates the 6-gate development workflow for implementing tasks. Manages state, dispatches specialist agents, and enforces gate requirements.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Captures metrics and learnings from completed development cycles. Enables continuous improvement by analyzing patterns across cycles.
Controlled plan execution with human review checkpoints - loads plan, executes in batches, pauses for feedback. Supports one-go (autonomous) or batch modes.
Gate 4 of development cycle - dispatches 6 specialized reviewers (code, business-logic, security, test, nil-safety, consequences) in parallel for comprehensive code review feedback.
Guide to the dev-team skills - specialist developer agents and 6-gate development cycle. Provides backend engineers (Go/TypeScript), frontend engineers, DevOps, SRE, and QA agents.
Skill discovery workflow and agent dispatch patterns for every conversation.
Generate beautiful, self-contained HTML pages that visually explain systems, code changes, plans, and data. Use when the user asks for a diagram, architecture overview, diff review, plan review, project recap, comparison table, or any visual explanation of technical concepts. Also use proactively when you are about to render a complex ASCII table (4+ rows or 3+ columns) — present it as a styled HTML page instead.
| name | ring:dev-cycle |
| description | Orchestrates the 6-gate development workflow for implementing tasks. Manages state, dispatches specialist agents, and enforces gate requirements. |
| license | MIT |
| compatibility | {"platforms":["opencode"]} |
| metadata | {"version":"1.0.0","author":"Lerian Studio","category":"workflow","trigger":["Tasks file provided (from pre-dev or ring:dev-refactor)","User wants to implement development task","/ring:dev-cycle command invoked"]} |
Before any gate execution, you MUST load Ring standards:
<fetch_required> https://raw.githubusercontent.com/LerianStudio/ring/main/CLAUDE.md </fetch_required>
Fetch URL above and extract: Agent Modification Verification requirements, Anti-Rationalization Tables requirements, and Critical Rules.
<block_condition>
If any condition is true, STOP and report blocker. Cannot proceed without Ring standards.
The development cycle orchestrator loads tasks/subtasks from PM team output (or manual task files) and executes through 10 gates (Gate 0–9) with deferred execution for infrastructure-dependent tests:
This keeps test code current with each feature while avoiding redundant container spin-ups during development.
MUST announce at start: "I'm using the ring:dev-cycle skill to orchestrate task execution through 10 gates (Gate 0–9). Gates 6-7 write tests per unit but execute at end of cycle."
See shared-patterns/shared-orchestrator-principle.md for full ORCHESTRATOR principle, role separation, forbidden/required actions, gate-to-agent mapping, and anti-rationalization table.
Summary: You orchestrate. Agents execute. If using Read/Write/Edit/Bash on source code → STOP. Dispatch agent.
This section defines exactly what the orchestrator CAN and CANNOT do.
| Action | Tool | Purpose |
|---|---|---|
| Read task files | Read | Load task definitions from docs/pre-dev/*/tasks.md or docs/ring:dev-refactor/*/tasks.md |
| Read state files | Read | Load/verify docs/ring:dev-cycle/current-cycle.json or docs/ring:dev-refactor/current-cycle.json |
| Read PROJECT_RULES.md | Read | Load project-specific rules |
| Write state files | Write | Persist cycle state to JSON |
| Track progress | TodoWrite | Maintain task list |
| Dispatch agents | Task | Send work to specialist agents |
| Ask user questions | AskUserQuestion | Get execution mode, approvals |
| WebFetch standards | WebFetch | Load Ring standards |
Any of these actions by orchestrator = IMMEDIATE VIOLATION. Dispatch agent instead.
If a task requires editing MORE than 3 files → MUST dispatch specialist agent.
This is not negotiable:
*.go, *.ts, *.tsx) → MUST dispatch agent┌─────────────────────────────────────────────────────────────────┐
│ CORRECT WORKFLOW ORDER │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Load task file (Read docs/pre-dev/*/tasks.md or docs/ring:dev-refactor/*/tasks.md) │
│ 2. Ask execution mode (AskUserQuestion) │
│ 3. Determine state path + Check/Load state (see State Path Selection) │
│ 4. WebFetch Ring Standards │
│ 5. ⛔ LOAD SUB-SKILL for current gate (Skill tool) │
│ 6. Execute sub-skill instructions (dispatch agent via Task) │
│ 7. Wait for agent completion │
│ 8. Verify agent output (Standards Coverage Table) │
│ 9. Update state (Write to JSON) │
│ 10. Proceed to next gate │
│ │
│ ════════════════════════════════════════════════════════════ │
│ ❌ WRONG: Load → Mode → Standards → Task(agent) directly │
│ ✅ RIGHT: Load → Mode → Standards → Skill(sub) → Task(agent) │
│ ════════════════════════════════════════════════════════════ │
└─────────────────────────────────────────────────────────────────┘
Before dispatching any agent, you MUST load the corresponding sub-skill first.
<cannot_skip>
Skill("ring:dev-implementation") → then Task(subagent_type="ring:backend-engineer-*", ...)Skill("ring:dev-devops") → then Task(subagent_type="ring:devops-engineer", ...)Skill("ring:dev-sre") → then Task(subagent_type="ring:sre", ...)Skill("ring:dev-unit-testing") → then Task(subagent_type="ring:qa-analyst", test_mode="unit", ...)Skill("ring:dev-fuzz-testing") → then Task(subagent_type="ring:qa-analyst", test_mode="fuzz", ...)Skill("ring:dev-property-testing") → then Task(subagent_type="ring:qa-analyst", test_mode="property", ...)Skill("ring:dev-integration-testing") → per unit: write/update tests + compile check (no execution); end of cycle: executeSkill("ring:dev-chaos-testing") → per unit: write/update tests + compile check (no execution); end of cycle: executeSkill("ring:requesting-code-review") → then 5x Task(...) in parallelSkill("ring:dev-validation") → N/A (verification only)
</cannot_skip>Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".
The workflow for each gate is:
1. Skill("[sub-skill-name]") ← Load sub-skill instructions
2. Follow sub-skill instructions ← Sub-skill tells you HOW to dispatch
3. Task(subagent_type=...) ← Dispatch agent as sub-skill instructs
4. Validate agent output ← Per sub-skill validation rules
5. Update state ← Record results
Validation: See shared-patterns/custom-prompt-validation.md for max length (500 chars), sanitization rules, gate protection, and conflict handling.
If custom_prompt is set in state, inject it into ALL agent dispatches:
Task tool:
subagent_type: "ring:backend-engineer-golang"
model: "opus"
prompt: |
**CUSTOM CONTEXT (from user):**
{state.custom_prompt}
---
**Standard Instructions:**
[... rest of agent prompt ...]
Rules for custom prompt:
custom_prompt from state file and inject into their agent dispatches (no explicit parameter passing needed)Example custom prompts and their effect:
| Custom Prompt | Effect on Agents |
|---|---|
| "Focus on error handling first" | Agents prioritize error-related acceptance criteria |
| "Use existing UserRepository interface" | Agents integrate with specified interface instead of creating new |
| "Deprioritize UI polish" | Gate 3 still enforces 85% coverage, but agents deprioritize non-functional UI tweaks |
| "Prioritize observability gaps" | SRE gate gets more attention, implementation focuses on instrumentation |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "I know what the sub-skill does" | Knowledge ≠ execution. Sub-skill has iteration logic. | Load Skill() first |
| "Task() directly is faster" | Faster ≠ correct. Sub-skill has validation rules. | Load Skill() first |
| "Sub-skill just wraps Task()" | Sub-skills have retry logic, fix dispatch, validation. | Load Skill() first |
| "I'll follow the pattern manually" | Manual = error-prone. Sub-skill is the pattern. | Load Skill() first |
Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "It's just one small file" | File count doesn't determine agent need. Language does. | DISPATCH specialist agent |
| "I already loaded the standards" | Loading standards ≠ permission to implement. Standards are for AGENTS. | DISPATCH specialist agent |
| "Agent dispatch adds overhead" | Overhead ensures compliance. Skip = skip verification. | DISPATCH specialist agent |
| "I can write Go/TypeScript" | Knowing language ≠ having Ring standards loaded. Agent has them. | DISPATCH specialist agent |
| "Just a quick fix" | "Quick" is irrelevant. all source changes require specialist. | DISPATCH specialist agent |
| "I'll read the file first to understand" | Reading source → temptation to edit. Agent reads for you. | DISPATCH specialist agent |
| "Let me check if tests pass first" | Agent runs tests in TDD cycle. You don't run tests. | DISPATCH specialist agent |
If you catch yourself doing any of these, STOP IMMEDIATELY:
🚨 RED FLAG: About to Read *.go or *.ts file
→ STOP. Dispatch agent instead.
🚨 RED FLAG: About to Write/Create source code
→ STOP. Dispatch agent instead.
🚨 RED FLAG: About to Edit source code
→ STOP. Dispatch agent instead.
🚨 RED FLAG: About to run "go test" or "npm test"
→ STOP. Agent runs tests, not you.
🚨 RED FLAG: Thinking "I'll just..."
→ STOP. "Just" is the warning word. Dispatch agent.
🚨 RED FLAG: Thinking "This is simple enough..."
→ STOP. Simplicity is irrelevant. Dispatch agent.
🚨 RED FLAG: Standards loaded, but next action is not Task tool
→ STOP. After standards, IMMEDIATELY dispatch agent.
If you violated orchestrator boundaries:
git checkout -- .)Sunk cost of direct work is IRRELEVANT. Agent dispatch is MANDATORY.
<block_condition>
You CANNOT proceed when blocked. Report and wait for resolution.
<cannot_skip>
No exceptions. User cannot override. Time pressure cannot override.
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Blocks deployment, security risk, data loss | Gate violation, skipped mandatory step |
| HIGH | Major functionality broken, standards violation | Missing tests, wrong agent dispatched |
| MEDIUM | Code quality, maintainability issues | Incomplete documentation, minor gaps |
| LOW | Best practices, optimization | Style improvements, minor refactoring |
Report all severities. Let user prioritize.
MEDIUM issues found in Gate 4 MUST be fixed. No exceptions.
| Request | Why It's WRONG | Required Action |
|---|---|---|
| "Can reviewer clarify if MEDIUM can defer?" | Reviewer already decided. MEDIUM means FIX. | Fix the issue, re-run reviewers |
| "Ask if this specific case is different" | Reviewer verdict accounts for context already. | Fix the issue, re-run reviewers |
| "Request exception for business reasons" | Reviewers know business context. Verdict is final. | Fix the issue, re-run reviewers |
Severity mapping is absolute:
No negotiation. No exceptions. No "special cases".
See shared-patterns/shared-pressure-resistance.md for universal pressure scenarios.
Gate-specific note: Execution mode selection affects CHECKPOINTS (user approval pauses), not GATES (quality checks). all gates execute regardless of mode.
See shared-patterns/shared-anti-rationalization.md for universal anti-rationalizations.
Gate-specific rationalizations:
| Excuse | Reality |
|---|---|
| "Automatic mode means faster" | Automatic mode skips CHECKPOINTS, not GATES. Same quality, less interruption. |
| "Automatic mode will skip review" | Automatic mode affects user approval pauses, not quality gates. all gates execute regardless. |
| "Defense in depth exists (frontend validates)" | Frontend can be bypassed. Backend is the last line. Fix at source. |
| "Backlog the Medium issue, it's documented" | Documented risk ≠ mitigated risk. Medium in Gate 4 = fix NOW, not later. |
| "Risk-based prioritization allows deferral" | Gates ARE the risk-based system. Reviewers define severity, not you. |
See shared-patterns/shared-red-flags.md for universal red flags.
If you catch yourself thinking any of those patterns, STOP immediately and return to gate execution.
The "just this once" pattern leads to complete gate erosion:
Day 1: "Skip review just this once" → Approved (precedent set)
Day 2: "Skip testing, we did it last time" → Approved (precedent extended)
Day 3: "Skip implementation checks, pattern established" → Approved (gates meaningless)
Day 4: Production incident from Day 1 code
Prevention rules:
A gate is COMPLETE only when all components finish successfully:
| Gate | Components Required | Partial = FAIL |
|---|---|---|
| 0.1 | TDD-RED: Failing test written + failure output captured | Test exists but no failure output = FAIL |
| 0.2 | TDD-GREEN: Implementation passes test | Code exists but test fails = FAIL |
| 0 | Both 0.1 and 0.2 complete | 0.1 done without 0.2 = FAIL |
| 1 | Dockerfile + docker-compose + .env.example | Missing any = FAIL |
| 2 | Structured JSON logs with trace correlation | Partial structured logs = FAIL |
| 3 | Unit test coverage ≥ 85% + all AC tested | 84% = FAIL |
| 4 | Fuzz tests with seed corpus ≥ 5 entries | Missing corpus = FAIL |
| 5 | Property-based tests for domain invariants | Missing property tests = FAIL |
| 6 | Integration tests with testcontainers | No testcontainers = FAIL |
| 7 | Chaos tests for failure scenarios | Missing chaos tests = FAIL |
| 8 | All 6 reviewers PASS | 5/6 reviewers = FAIL |
| 9 | Explicit "APPROVED" from user | "Looks good" = not approved |
CRITICAL for Gate 8: Running 5 of 6 reviewers is not a partial pass - it's a FAIL. Re-run all 6 reviewers.
Anti-Rationalization for Partial Gates:
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "5 of 6 reviewers passed" | Gate 8 requires all 6. 5/6 = 0/6. | Re-run all 6 reviewers |
| "Gate mostly complete" | Mostly ≠ complete. Binary: done or not done. | Complete all components |
| "Can finish remaining in next cycle" | Gates don't carry over. Complete NOW. | Finish current gate |
| "Core components done, optional can wait" | No component is optional within a gate. | Complete all components |
| "Unit tests are enough, skip fuzz/property" | Each test type catches different bugs. All are MANDATORY. | Execute all testing gates (3-7) |
| "No external dependencies, skip integration" | Integration testing is MANDATORY. Write tests per unit, execute at end of cycle. | Write Gate 6 tests per unit, execute at end |
Gates MUST execute in order: 0 → 1 → 2 → 3 → 4 → 5 → 6(write) → 7(write) → 8 → 9. All 10 gates are MANDATORY.
Deferred Execution Model for Gates 6-7:
| Violation | Why It's WRONG | Consequence |
|---|---|---|
| Skip Gate 1 (DevOps) | "No infra changes" | Code without container = works on my machine only |
| Skip Gate 2 (SRE) | "Observability later" | Blind production = debugging nightmare |
| Skip Gate 4 (Fuzz) | "Unit tests are enough" | Edge cases and crashes not discovered |
| Skip Gate 5 (Property) | "Too complex" | Domain invariant violations not detected |
| Skip Gate 6 (Integration) | "No external dependencies" | Internal integration bugs surface in production |
| Skip Gate 7 (Chaos) | "Infra is reliable" | System fails under real-world conditions |
| Reorder Gates | "Review before test" | Reviewing untested code wastes reviewer time |
| Parallel Gates | "Run 3 and 4 together" | Dependencies exist. Order is intentional. |
All testing gates (3-7) are MANDATORY. No exceptions. No skip reasons.
Gates are not parallelizable across different gates. Sequential execution is MANDATORY.
| Gate | Skill | Purpose | Agent | Per Unit | Standards Module |
|---|---|---|---|---|---|
| 0 | ring:dev-implementation | Write code following TDD | Based on task language/domain | Write + Run | core.md, domain.md |
| 1 | ring:dev-devops | Infrastructure and deployment | ring:devops-engineer | Write + Run | devops.md |
| 2 | ring:dev-sre | Observability (health, logging, tracing) | ring:sre | Write + Run | sre.md |
| 3 | ring:dev-unit-testing | Unit tests for acceptance criteria | ring:qa-analyst (test_mode: unit) | Write + Run | testing-unit.md |
| 4 | ring:dev-fuzz-testing | Fuzz tests for edge cases and crashes | ring:qa-analyst (test_mode: fuzz) | Write + Run | testing-fuzz.md |
| 5 | ring:dev-property-testing | Property-based tests for domain invariants | ring:qa-analyst (test_mode: property) | Write + Run | testing-property.md |
| 6 | ring:dev-integration-testing | Integration tests with testcontainers | ring:qa-analyst (test_mode: integration) | Write only | testing-integration.md |
| 7 | ring:dev-chaos-testing | Chaos tests for failure scenarios | ring:qa-analyst (test_mode: chaos) | Write only | testing-chaos.md |
| 8 | ring:requesting-code-review | Parallel code review (6 reviewers) | ring:code-reviewer, ring:business-logic-reviewer, ring:security-reviewer, ring:nil-safety-reviewer, ring:test-reviewer, ring:consequences-reviewer | Run | N/A |
| 9 | ring:dev-validation | Final acceptance validation | N/A (verification) | Run | N/A |
All gates are MANDATORY. No exceptions. No skip reasons.
Gates 6-7 Deferred Execution: Test code is written/updated per unit to stay current. Actual test execution (with containers) happens once at end of cycle.
PM Team Output → Dev Team Execution (/ring:dev-cycle)
| Input Type | Path | Structure |
|---|---|---|
| Tasks only | docs/pre-dev/{feature}/tasks.md | T-001, T-002, T-003 with requirements + acceptance criteria |
| Tasks + Subtasks | docs/pre-dev/{feature}/ | tasks.md + subtasks/{task-id}/ST-XXX-01.md, ST-XXX-02.md... |
Core Principle: Each execution unit passes through all 10 gates. Gates 6-7 write test code per unit but defer execution to end of cycle.
Per-Unit Flow: Unit → Gate 0→1→2→3→4→5→6(write)→7(write)→8→9 → 🔒 Unit Checkpoint → 🔒 Task Checkpoint → Next Unit End-of-Cycle Flow: All units done → Gate 6(execute)→7(execute) → Final Commit → Feedback
| Scenario | Execution Unit | Gates Per Unit | End of Cycle |
|---|---|---|---|
| Task without subtasks | Task itself | 10 gates (6-7 write only) | Gate 6-7 execute |
| Task with subtasks | Each subtask | 10 gates per subtask (6-7 write only) | Gate 6-7 execute |
Why deferred execution for Gates 6-7:
User selects when commits happen (Step 7 of initialization).
| Option | When Commit Happens | Use Case |
|---|---|---|
| (a) Per subtask | After each subtask passes Gate 9 | Fine-grained history, easy rollback per subtask |
| (b) Per task | After all subtasks of a task complete | Logical grouping, one commit per feature chunk |
| (c) At the end | After entire cycle completes | Single commit with all changes, clean history |
| Timing | Message Format | Example |
|---|---|---|
| Per subtask | feat({subtask_id}): {subtask_title} | feat(ST-001-02): implement user authentication handler |
| Per task | feat({task_id}): {task_title} | feat(T-001): implement user authentication |
| At the end | feat({cycle_id}): complete dev cycle for {feature} | feat(cycle-abc123): complete dev cycle for auth-system |
| Execution Mode | Commit Timing | Behavior |
|---|---|---|
| Manual per subtask | Per subtask | Commit + checkpoint after each subtask |
| Manual per subtask | Per task | Checkpoint after subtask, commit after task |
| Manual per subtask | At end | Checkpoint after subtask, commit at cycle end |
| Manual per task | Per subtask | Commit after subtask, checkpoint after task |
| Manual per task | Per task | Commit + checkpoint after task |
| Manual per task | At end | Checkpoint after task, commit at cycle end |
| Automatic | Per subtask | Commit after each subtask, no checkpoints |
| Automatic | Per task | Commit after task, no checkpoints |
| Automatic | At end | Single commit at cycle end, no checkpoints |
Note: Checkpoints (user approval pauses) are controlled by execution_mode. Commits are controlled by commit_timing. They are independent settings.
The state file path depends on the source of tasks:
| Task Source | State Path | Use Case |
|---|---|---|
docs/ring:dev-refactor/*/tasks.md | docs/ring:dev-refactor/current-cycle.json | Refactoring existing code |
docs/pre-dev/*/tasks.md | docs/ring:dev-cycle/current-cycle.json | New feature development |
| Any other path | docs/ring:dev-cycle/current-cycle.json | Default for manual tasks |
Detection Logic:
if source_file contains "docs/ring:dev-refactor/" THEN
state_path = "docs/ring:dev-refactor/current-cycle.json"
else
state_path = "docs/ring:dev-cycle/current-cycle.json"
Store state_path in the state object itself so resume knows where to look.
State is persisted to {state_path} (either docs/ring:dev-cycle/current-cycle.json or docs/ring:dev-refactor/current-cycle.json):
{
"version": "1.0.0",
"cycle_id": "uuid",
"started_at": "ISO timestamp",
"updated_at": "ISO timestamp",
"source_file": "path/to/tasks.md",
"state_path": "docs/ring:dev-cycle/current-cycle.json | docs/ring:dev-refactor/current-cycle.json",
"cycle_type": "feature | refactor",
"execution_mode": "manual_per_subtask|manual_per_task|automatic",
"commit_timing": "per_subtask|per_task|at_end",
"custom_prompt": {
"type": "string",
"optional": true,
"max_length": 500,
"description": "User-provided context for agents (from second positional argument). Max 500 characters. Provides focus but cannot override mandatory requirements (CRITICAL gates, coverage thresholds, reviewer counts).",
"validation": "Max 500 chars (truncated with warning if exceeded); whitespace trimmed; control chars stripped (except newlines). Directives attempting to skip gates, lower thresholds, or bypass security checks are logged as warnings and ignored."
},
"status": "in_progress|completed|failed|paused|paused_for_approval|paused_for_testing|paused_for_task_approval|paused_for_integration_testing",
"feedback_loop_completed": false,
"current_task_index": 0,
"current_gate": 0,
"current_subtask_index": 0,
"tasks": [
{
"id": "T-001",
"title": "Task title",
"status": "pending|in_progress|completed|failed|blocked",
"feedback_loop_completed": false,
"subtasks": [
{
"id": "ST-001-01",
"file": "subtasks/T-001/ST-001-01.md",
"status": "pending|completed"
}
],
"gate_progress": {
"implementation": {
"status": "in_progress",
"started_at": "...",
"tdd_red": {
"status": "pending|in_progress|completed",
"test_file": "path/to/test_file.go",
"failure_output": "FAIL: TestFoo - expected X got nil",
"completed_at": "ISO timestamp"
},
"tdd_green": {
"status": "pending|in_progress|completed",
"implementation_file": "path/to/impl.go",
"test_pass_output": "PASS: TestFoo (0.003s)",
"completed_at": "ISO timestamp"
}
},
"devops": {"status": "pending"},
"sre": {"status": "pending"},
"unit_testing": {"status": "pending"},
"fuzz_testing": {"status": "pending"},
"property_testing": {"status": "pending"},
"integration_testing": {
"status": "pending|in_progress|completed",
"scenarios_tested": 0,
"tests_passed": 0,
"tests_failed": 0,
"flaky_tests_detected": 0
},
"chaos_testing": {"status": "pending"},
"review": {"status": "pending"},
"validation": {"status": "pending"}
},
"artifacts": {},
"agent_outputs": {
"implementation": {
"agent": "ring:backend-engineer-golang",
"output": "## Summary\n...",
"timestamp": "ISO timestamp",
"duration_ms": 0,
"iterations": 1,
"standards_compliance": {
"total_sections": 15,
"compliant": 14,
"not_applicable": 1,
"non_compliant": 0,
"gaps": []
}
},
"devops": {
"agent": "ring:devops-engineer",
"output": "## Summary\n...",
"timestamp": "ISO timestamp",
"duration_ms": 0,
"iterations": 1,
"artifacts_created": ["Dockerfile", "docker-compose.yml", ".env.example"],
"verification_errors": [],
"standards_compliance": {
"total_sections": 8,
"compliant": 8,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"sre": {
"agent": "ring:sre",
"output": "## Summary\n...",
"timestamp": "ISO timestamp",
"duration_ms": 0,
"iterations": 1,
"instrumentation_coverage": "92%",
"validation_errors": [],
"standards_compliance": {
"total_sections": 10,
"compliant": 10,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"unit_testing": {
"agent": "ring:qa-analyst",
"test_mode": "unit",
"output": "## Summary\n...",
"verdict": "PASS",
"coverage_actual": 87.5,
"coverage_threshold": 85,
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"failures": [],
"uncovered_criteria": [],
"standards_compliance": {
"total_sections": 6,
"compliant": 6,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"fuzz_testing": {
"agent": "ring:qa-analyst",
"test_mode": "fuzz",
"output": "## Summary\n...",
"verdict": "PASS",
"corpus_entries": 5,
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"standards_compliance": {
"total_sections": 5,
"compliant": 5,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"property_testing": {
"agent": "ring:qa-analyst",
"test_mode": "property",
"output": "## Summary\n...",
"verdict": "PASS",
"properties_tested": 3,
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"standards_compliance": {
"total_sections": 5,
"compliant": 5,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"integration_testing": {
"agent": "ring:qa-analyst",
"test_mode": "integration",
"output": "## Summary\n...",
"verdict": "PASS",
"scenarios_tested": 5,
"tests_passed": 5,
"tests_failed": 0,
"flaky_tests_detected": 0,
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"standards_compliance": {
"total_sections": 10,
"compliant": 10,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"chaos_testing": {
"agent": "ring:qa-analyst",
"test_mode": "chaos",
"output": "## Summary\n...",
"verdict": "PASS",
"failure_scenarios_tested": 4,
"recovery_verified": true,
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"standards_compliance": {
"total_sections": 5,
"compliant": 5,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"review": {
"iterations": 1,
"timestamp": "ISO timestamp",
"duration_ms": 0,
"code_reviewer": {
"agent": "ring:code-reviewer",
"output": "...",
"verdict": "PASS",
"timestamp": "...",
"issues": [],
"standards_compliance": {
"total_sections": 12,
"compliant": 12,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"business_logic_reviewer": {
"agent": "ring:business-logic-reviewer",
"output": "...",
"verdict": "PASS",
"timestamp": "...",
"issues": [],
"standards_compliance": {
"total_sections": 8,
"compliant": 8,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
},
"security_reviewer": {
"agent": "ring:security-reviewer",
"output": "...",
"verdict": "PASS",
"timestamp": "...",
"issues": [],
"standards_compliance": {
"total_sections": 10,
"compliant": 10,
"not_applicable": 0,
"non_compliant": 0,
"gaps": []
}
}
},
"validation": {
"result": "approved|rejected",
"timestamp": "ISO timestamp"
}
}
}
],
"metrics": {
"total_duration_ms": 0,
"gate_durations": {},
"review_iterations": 0,
"testing_iterations": 0
}
}
These schemas enable ring:dev-feedback-loop to analyze issues without parsing raw output.
{
"section": "Error Handling (MANDATORY)",
"status": "❌",
"reason": "Missing error wrapping with context",
"file": "internal/handler/user.go",
"line": 45,
"evidence": "return err // should wrap with additional context"
}
{
"test_name": "TestUserCreate_InvalidEmail",
"test_file": "internal/handler/user_test.go",
"error_type": "assertion",
"expected": "ErrInvalidEmail",
"actual": "nil",
"message": "Expected validation error for invalid email format",
"stack_trace": "user_test.go:42 → user.go:28"
}
{
"severity": "MEDIUM",
"category": "error-handling",
"description": "Error not wrapped with context before returning",
"file": "internal/handler/user.go",
"line": 45,
"suggestion": "Use fmt.Errorf(\"failed to create user: %w\", err)",
"fixed": false,
"fixed_in_iteration": null
}
{
"check": "docker_build",
"status": "FAIL",
"error": "COPY failed: file not found in build context: go.sum",
"suggestion": "Ensure go.sum exists and is not in .dockerignore"
}
{
"check": "structured_logging",
"status": "FAIL",
"file": "internal/handler/user.go",
"line": 32,
"error": "Using fmt.Printf instead of structured logger",
"suggestion": "Use logger.Info().Str(\"user_id\", id).Msg(\"user created\")"
}
Each gate MUST populate its structured fields when saving to state:
| Gate | Fields to Populate |
|---|---|
| Gate 0 (Implementation) | standards_compliance (total, compliant, gaps[]) |
| Gate 1 (DevOps) | standards_compliance + verification_errors[] |
| Gate 2 (SRE) | standards_compliance + validation_errors[] |
| Gate 3 (Unit Testing) | standards_compliance + failures[] + uncovered_criteria[] |
| Gate 4 (Fuzz Testing) | standards_compliance + corpus_entries |
| Gate 5 (Property Testing) | standards_compliance + properties_tested |
| Gate 6 (Integration Testing) | standards_compliance + scenarios_tested + tests_passed + tests_failed + flaky_tests_detected |
| Gate 7 (Chaos Testing) | standards_compliance + failure_scenarios_tested + recovery_verified |
| Gate 8 (Review) | standards_compliance per reviewer + issues[] per reviewer |
All gates track standards_compliance:
total_sections: Count from agent's standards file (via standards-coverage-table.md)compliant: Sections marked ✅ in Standards Coverage Tablenot_applicable: Sections marked N/Anon_compliant: Sections marked ❌ (MUST be 0 to pass gate)gaps[]: Detailed info for each ❌ section (even if later fixed)Empty arrays [] indicate no issues found - this is valid data for feedback-loop.
"Update state" means BOTH update the object and write to file. Not just in-memory.
You MUST execute these steps after completing any gate (0, 1, 2, 3, 4, or 5):
# Step 1: Update state object with gate results
state.tasks[current_task_index].gate_progress.[gate_name].status = "completed"
state.tasks[current_task_index].gate_progress.[gate_name].completed_at = "[ISO timestamp]"
state.current_gate = [next_gate_number]
state.updated_at = "[ISO timestamp]"
# Step 2: Write to file (MANDATORY - use Write tool)
Write tool:
file_path: [state.state_path] # Use state_path from state object
content: [full JSON state]
# Step 3: Verify persistence (MANDATORY - use Read tool)
Read tool:
file_path: [state.state_path] # Use state_path from state object
# Confirm current_gate and gate_progress match expected values
| After | MUST Update | MUST Write File |
|---|---|---|
| Gate 0.1 (TDD-RED) | tdd_red.status, tdd_red.failure_output | ✅ YES |
| Gate 0.2 (TDD-GREEN) | tdd_green.status, implementation.status | ✅ YES |
| Gate 1 (DevOps) | devops.status, agent_outputs.devops | ✅ YES |
| Gate 2 (SRE) | sre.status, agent_outputs.sre | ✅ YES |
| Gate 3 (Unit Testing) | unit_testing.status, agent_outputs.unit_testing | ✅ YES |
| Gate 4 (Fuzz Testing) | fuzz_testing.status, agent_outputs.fuzz_testing | ✅ YES |
| Gate 5 (Property Testing) | property_testing.status, agent_outputs.property_testing | ✅ YES |
| Gate 6 (Integration Testing) | integration_testing.status, agent_outputs.integration_testing | ✅ YES |
| Gate 7 (Chaos Testing) | chaos_testing.status, agent_outputs.chaos_testing | ✅ YES |
| Gate 8 (Review) | review.status, agent_outputs.review | ✅ YES |
| Gate 9 (Validation) | validation.status, task status | ✅ YES |
| Step 11.1 (Unit Approval) | status = "paused_for_approval" | ✅ YES |
| Step 11.2 (Task Approval) | status = "paused_for_task_approval" | ✅ YES |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "I'll save state at the end" | Crash/timeout loses all progress | Save after each gate |
| "State is in memory, that's updated" | Memory is volatile. File is persistent. | Write to JSON file |
| "Only save on checkpoints" | Gates without saves = unrecoverable on resume | Save after every gate |
| "Write tool is slow" | Write takes <100ms. Lost progress takes hours. | Write after every gate |
| "I updated the state variable" | Variable ≠ file. Without Write tool, nothing persists. | Use Write tool explicitly |
After each gate, the state file MUST reflect:
current_gate = next gate numberupdated_at = recent timestampstatus = "completed"If verification fails → State was not persisted. Re-execute Write tool.
NON-NEGOTIABLE. Cycle CANNOT proceed without project standards.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Check: Does docs/PROJECT_RULES.md exist? │
│ │
│ ├── YES → Proceed to Step 1 (Initialize or Resume) │
│ │ │
│ └── no → ASK: "Is this a LEGACY project (created without PM workflow)?" │
│ │ │
│ ├── YES (legacy project) → LEGACY PROJECT ANALYSIS: │
│ │ Step 1: Dispatch ring:codebase-explorer (technical info only) │
│ │ Step 2: Ask 3 questions (what agent can't determine): │
│ │ 1. What do you need help with? │
│ │ 2. Any external APIs not visible in code? │
│ │ 3. Any specific technology not in Ring Standards? │
│ │ Step 3: Generate PROJECT_RULES.md (deduplicated from Ring) │
│ │ Note: Business rules belong in PRD, not in PROJECT_RULES │
│ │ → Proceed to Step 1 │
│ │ │
│ └── no (new project) → ASK: "Do you have PRD, TRD, or Feature Map?" │
│ │ │
│ ├── YES (has PM docs) → "Please provide the file path(s)" │
│ │ → Read PRD/TRD/Feature Map → Extract info │
│ │ → Generate PROJECT_RULES.md │
│ │ → Ask supplementary questions if info is incomplete │
│ │ → Save and proceed to Step 1 │
│ │ │
│ └── no (no PM docs) → ⛔ HARD BLOCK: │
│ "PM documents are REQUIRED for new projects. │
│ Run /ring:pre-dev-full or /ring:pre-dev-feature first." │
│ → STOP (cycle cannot proceed) │
└─────────────────────────────────────────────────────────────────────────────┘
# Check if file exists
Read tool:
file_path: "docs/PROJECT_RULES.md"
# If file exists and has content → Proceed to Step 1
# If file does not exist or is empty → Continue to Step 0.2
Use AskUserQuestion:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 PROJECT_RULES.md not FOUND │
├─────────────────────────────────────────────────────────────────┤
│ │
│ I need to create docs/PROJECT_RULES.md to understand your │
│ project's specific conventions and domain. │
│ │
│ First, I need to know: Is this a LEGACY project? │
│ │
│ A legacy project is one that was created WITHOUT using the │
│ PM team workflow (no PRD, TRD, or Feature Map documents). │
│ │
└─────────────────────────────────────────────────────────────────┘
"Is this a legacy project (created without PM team workflow)?"
(a) Yes, this is a legacy project (b) No, this is a new project following Ring workflow
Go to Step 0.2.1 (Legacy Project Analysis)
Go to Step 0.3 (Check for PM Documents)
For legacy projects, analyze codebase for TECHNICAL information only:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 LEGACY PROJECT ANALYSIS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Since this is a legacy project, I'll analyze the codebase │
│ for TECHNICAL information (not business rules). │
│ │
│ Step 1: Automated analysis (ring:codebase-explorer) │
│ Step 2: Ask for project-specific tech not in Ring Standards │
│ Step 3: Generate PROJECT_RULES.md (deduplicated) │
│ │
│ Note: Business rules belong in PRD/product docs, not here. │
│ │
└─────────────────────────────────────────────────────────────────┘
⛔ You MUST use the Task tool to dispatch ring:codebase-explorer. This is not implicit.
Dispatch ring:codebase-explorer to analyze the legacy project for TECHNICAL information:
Action: Use Task tool with EXACTLY these parameters:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ⛔ If Task tool not used → Analysis does not happen → PROJECT_RULES.md INVALID │
└─────────────────────────────────────────────────────────────────────────────────┘
# Agent 1: Codebase Explorer - Technical Analysis
Task tool:
subagent_type: "ring:codebase-explorer"
model: "opus"
description: "Analyze legacy project for PROJECT_RULES.md"
prompt: |
Analyze this LEGACY codebase to extract technical information for PROJECT_RULES.md.
This is an existing project created without PM documentation.
Your job is to understand what exists in the code.
**Extract:**
1. **Project Structure:** Directory layout, module organization
2. **Technical Stack:** Languages, frameworks, databases, external services
3. **Architecture Patterns:** Clean Architecture, MVC, microservices, etc.
4. **Existing Features:** Main modules, endpoints, capabilities
5. **Internal Libraries:** Shared packages, utilities
6. **Configuration:** Environment variables, config patterns
7. **Database:** Schema patterns, migrations, ORM usage
8. **External Integrations:** APIs consumed, message queues
**Output format:**
## Technical Analysis (Legacy Project)
### Project Overview
[What this project appears to do based on code analysis]
### Technical Stack
- Language: [detected]
- Framework: [detected]
- Database: [detected]
- External Services: [detected]
### Architecture Patterns
[Detected patterns]
### Existing Features
[List of features/modules found]
### Project Structure
[Directory layout explanation]
### Configuration
[Env vars, config files found]
### External Integrations
[APIs, services detected]
Note: Business logic analysis is not needed for PROJECT_RULES.md. Business rules belong in PRD/product docs, not technical project rules.
After agent completes, confirm:
ring:codebase-explorer returned "## Technical Analysis (Legacy Project)" sectionIf agent failed or returned empty output → Re-dispatch. Cannot proceed without technical analysis.
After agents complete, ask only what they couldn't determine from code:
┌─────────────────────────────────────────────────────────────────┐
│ ✓ Codebase Analysis Complete │
├─────────────────────────────────────────────────────────────────┤
│ │
│ I've analyzed your codebase. Now I need a few details that │
│ only you can provide (not visible in the code). │
│ │
└─────────────────────────────────────────────────────────────────┘
Use AskUserQuestion for each:
| # | Question | Why Agents Can't Determine This |
|---|---|---|
| 1 | What do you need help with? (Current task/feature/fix) | Future intent, not in code |
| 2 | Any external APIs or services not visible in code? (Third-party integrations planned) | Planned integrations, not yet in code |
| 3 | Any specific technology not in Ring Standards? (Message broker, cache, etc.) | Project-specific tech not in Ring |
Note: Business rules belong in PRD/product docs, not in PROJECT_RULES.md.
Create tool:
file_path: "docs/PROJECT_RULES.md"
content: |
# Project Rules
> Ring Standards apply automatically. This file documents only what Ring does not cover.
> For error handling, logging, testing, architecture, lib-commons → See Ring Standards (auto-loaded by agents)
> Generated from legacy project analysis.
## What Ring Standards Already Cover (DO not ADD HERE)
The following are defined in Ring Standards and MUST not be duplicated:
- Error handling patterns (no panic, wrap errors)
- Logging standards (structured JSON, zerolog/zap)
- Testing patterns (table-driven tests, mocks)
- Architecture patterns (Hexagonal, Clean Architecture)
- Observability (OpenTelemetry, trace correlation)
- lib-commons usage and patterns
- API directory structure
---
## Tech Stack (Not in Ring Standards)
[From ring:codebase-explorer: Technologies not covered by Ring Standards]
[e.g., specific message broker, specific cache, DB if not PostgreSQL]
| Technology | Purpose | Notes |
|------------|---------|-------|
| [detected] | [purpose] | [notes] |
## Non-Standard Directory Structure
[From ring:codebase-explorer: Directories that deviate from Ring's standard API structure]
[e.g., workers/, consumers/, polling/]
| Directory | Purpose | Pattern |
|-----------|---------|---------|
| [detected] | [purpose] | [pattern] |
## External Integrations
[From ring:codebase-explorer: Third-party services specific to this project]
| Service | Purpose | Docs |
|---------|---------|------|
| [detected] | [purpose] | [link] |
## Environment Configuration
[From ring:codebase-explorer: Project-specific env vars not covered by Ring]
| Variable | Purpose | Example |
|----------|---------|---------|
| [detected] | [purpose] | [example] |
## Domain Terminology
[From codebase analysis: Technical names used in this codebase]
| Term | Definition | Used In |
|------|------------|---------|
| [detected] | [definition] | [location] |
---
*Generated: [ISO timestamp]*
*Source: Legacy project analysis (ring:codebase-explorer)*
*Ring Standards Version: [version from WebFetch]*
┌─────────────────────────────────────────────────────────────────┐
│ ✓ PROJECT_RULES.md Generated for Legacy Project │
├─────────────────────────────────────────────────────────────────┤
│ │
│ I analyzed your codebase using: │
│ • ring:codebase-explorer (technical patterns, stack, structure) │
│ │
│ Combined with your input on: │
│ • Current development goal │
│ • External integrations │
│ • Project-specific technology │
│ │
│ Generated: docs/PROJECT_RULES.md │
│ │
│ Note: Ring Standards (error handling, logging, testing, etc.) │
│ are not duplicated - agents load them automatically via WebFetch│
│ │
│ Please review the file and make any corrections needed. │
│ │
└─────────────────────────────────────────────────────────────────┘
Use AskUserQuestion:
Proceed to Step 1
For NEW projects (not legacy), ask about PM documents:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 NEW PROJECT - PM DOCUMENTS CHECK │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Since this is a new project following Ring workflow, you │
│ should have PM documents from the pre-dev workflow. │
│ │
│ Do you have any of these PM documents? │
│ • PRD (Product Requirements Document) │
│ • TRD (Technical Requirements Document) │
│ • Feature Map (from ring:pre-dev-feature-map skill) │
│ │
└─────────────────────────────────────────────────────────────────┘
"Do you have PRD, TRD, or Feature Map documents for this project?"
(a) Yes, I have PM documents (b) No, I don't have these documents
"Please provide the file path(s) to your PM documents:
- PRD path (or 'skip' if none):
- TRD path (or 'skip' if none):
- Feature Map path (or 'skip' if none): "
Typical PM team output structure:
docs/pre-dev/{feature-name}/
├── prd.md → PRD path: docs/pre-dev/auth-system/prd.md
├── trd.md → TRD path: docs/pre-dev/auth-system/trd.md
├── feature-map.md → Feature Map path: docs/pre-dev/auth-system/feature-map.md
├── api-design.md
├── data-model.md
└── tasks.md
/ring:pre-dev-full output: docs/pre-dev/{feature}/prd.md, trd.md, feature-map.md/ring:pre-dev-feature output: docs/pre-dev/{feature}/prd.md, feature-map.mdrequirements/, specs/)Go to Step 0.3.1 (Generate from PM Documents)
HARD BLOCK (Step 0.3.2)
# Read PRD if provided
Read tool:
file_path: "[user-provided PRD path]"
# Read TRD if provided
Read tool:
file_path: "[user-provided TRD path]"
# Read Feature Map if provided
Read tool:
file_path: "[user-provided Feature Map path]"
⛔ DEDUPLICATION RULE: Extract only what Ring Standards DO NOT cover.
| From PRD | Extract For PROJECT_RULES.md | Note |
|---|---|---|
| Domain terms, entities | Domain Terminology | Technical names only |
| External service mentions | External Integrations | Third-party APIs |
| ❌ Stays in PRD, not PROJECT_RULES | ||
| ❌ Ring Standards covers this |
| From TRD | Extract For PROJECT_RULES.md | Note |
|---|---|---|
| Tech stack not in Ring | Tech Stack (Not in Ring) | Only non-standard tech |
| External APIs | External Integrations | Third-party services |
| Non-standard directories | Non-Standard Directory Structure | Workers, consumers, etc. |
| ❌ Ring Standards covers this | ||
| ❌ Ring Standards covers this |
| From Feature Map | Extract For PROJECT_RULES.md | Note |
|---|---|---|
| Technology choices not in Ring | Tech Stack (Not in Ring) | Only if not in Ring |
| External dependencies | External Integrations | Third-party services |
| ❌ Ring Standards covers this |
Create tool:
file_path: "docs/PROJECT_RULES.md"
content: |
# Project Rules
> ⛔ IMPORTANT: Ring Standards are not automatic. Agents MUST WebFetch them before implementation.
> This file documents only project-specific information not covered by Ring Standards.
> Generated from PM documents (PRD/TRD/Feature Map).
>
> Ring Standards URLs:
> - Go: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md
> - TypeScript: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md
## What Ring Standards Cover (DO not DUPLICATE HERE)
The following are defined in Ring Standards and MUST not be duplicated in this file:
- Error handling patterns (no panic, wrap errors)
- Logging standards (structured JSON via lib-commons)
- Testing patterns (table-driven tests, mocks)
- Architecture patterns (Hexagonal, Clean Architecture)
- Observability (OpenTelemetry via lib-commons)
- lib-commons / lib-common-js usage and patterns
- API directory structure (Lerian pattern)
- Database connections (PostgreSQL, MongoDB, Redis via lib-commons)
- Bootstrap pattern (config.go, service.go, server.go)
**Agents MUST WebFetch Ring Standards and output Standards Coverage Table.**
---
## Tech Stack (Not in Ring Standards)
[From TRD/Feature Map: only technologies not covered by Ring Standards]
| Technology | Purpose | Notes |
|------------|---------|-------|
| [detected] | [purpose] | [notes] |
## Non-Standard Directory Structure
[From TRD: Directories that deviate from Ring's standard API structure]
| Directory | Purpose | Pattern |
|-----------|---------|---------|
| [detected] | [purpose] | [pattern] |
## External Integrations
[From TRD/PRD: Third-party services specific to this project]
| Service | Purpose | Docs |
|---------|---------|------|
| [detected] | [purpose] | [link] |
## Environment Configuration
[From TRD: Project-specific env vars not covered by Ring]
| Variable | Purpose | Example |
|----------|---------|---------|
| [detected] | [purpose] | [example] |
## Domain Terminology
[From PRD: Technical names used in this codebase]
| Term | Definition | Used In |
|------|------------|---------|
| [detected] | [definition] | [location] |
---
*Generated from: [PRD path], [TRD path], [Feature Map path]*
*Ring Standards Version: [version from WebFetch]*
*Generated: [ISO timestamp]*
If any section is empty or incomplete, ask supplementary questions:
| Missing Section | Supplementary Question |
|---|---|
| Tech Stack (Not in Ring) | "Any technology not covered by Ring Standards (message broker, cache, etc.)?" |
| External Integrations | "Any third-party APIs or external services?" |
| Domain Terminology | "What are the main entities/classes in this codebase?" |
| Non-Standard Directories | "Any directories that don't follow standard API structure (workers, consumers)?" |
Note: Do not ask about architecture, error handling, logging, testing - Ring Standards covers these.
Present to user for review, then proceed to Step 1.
┌─────────────────────────────────────────────────────────────────┐
│ ⛔ CANNOT PROCEED - PM DOCUMENTS REQUIRED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Development cannot start without PM documents. │
│ │
│ You MUST create PRD, TRD, and/or Feature Map documents first │
│ using PM team skills: │
│ │
│ /ring:pre-dev-full → For features ≥2 days (9 gates) │
│ /ring:pre-dev-feature → For features <2 days (4 gates) │
│ │
│ These commands will guide you through creating: │
│ • PRD (Product Requirements Document) │
│ • TRD (Technical Requirements Document) │
│ • Feature Map (technology choices, feature relationships) │
│ │
│ After completing pre-dev workflow, run /ring:dev-cycle again. │
│ │
└─────────────────────────────────────────────────────────────────┘
STOP EXECUTION. Do not proceed to Step 1.
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Skip PM docs, I'll add them later" | Later = never. No PM docs = no project context = agents guessing. | Run /ring:pre-dev-full or /ring:pre-dev-feature NOW |
| "Project is simple, doesn't need PM docs" | Simple projects still need domain context defined upfront. | Create PM documents first |
| "I know what I want to build" | Your knowledge ≠ documented knowledge agents can use. | Document in PRD/TRD/Feature Map |
| "PM workflow takes too long" | PM workflow takes 30-60 min. Rework from unclear requirements takes days. | Invest time upfront |
| "Just let me start coding" | Coding without requirements = building the wrong thing. | Requirements first, code second |
| "It's legacy but I don't want to answer questions" | Legacy analysis takes ~5 min. Without it, agents have zero context. | Answer the 4 questions |
| "Legacy project is too complex to explain" | Start with high-level answers. PROJECT_RULES.md can be refined later. | Provide what you know NOW |
| User Says | Your Response |
|---|---|
| "Just skip this, I'll create PM docs later" | "PM documents are REQUIRED for new projects. Without them, agents cannot understand your project's domain context or technical requirements. Run /ring:pre-dev-full or /ring:pre-dev-feature first." |
| "I don't need formal documents" | "PM documents are the source of truth for PROJECT_RULES.md. Development cannot start without documented requirements." |
| "This is just a quick prototype" | "Even prototypes need clear requirements. /ring:pre-dev-feature takes ~30 minutes and prevents hours of rework." |
| "I already explained what I want verbally" | "Verbal explanations cannot be used by agents. Requirements MUST be documented in PRD/TRD/Feature Map files." |
| "It's a legacy project but skip the questions" | "The legacy analysis (ring:codebase-explorer + 3 questions) is the only way I can understand your project. It takes ~5 minutes and enables me to help you effectively." |
| "I'll fill in PROJECT_RULES.md myself" | "That works! Create docs/PROJECT_RULES.md with: Tech Stack (not in Ring), External Integrations, Domain Terminology. Do not duplicate Ring Standards content. Then run /ring:dev-cycle again." |
Input: Custom instructions string without a task file path
Example: /ring:dev-cycle "Implement multi-tenant support with organization_id in all entities"
When custom instructions are provided without a tasks file, ring:dev-cycle generates tasks internally:
ring:codebase-explorer to understand project structureTask tool:
subagent_type: "ring:codebase-explorer"
model: "opus"
prompt: |
Analyze this codebase to support the following implementation request:
**User Request:** {prompt}
Provide:
1. Relevant files and patterns for this request
2. Suggested task breakdown (T-001, T-002, etc.)
3. Acceptance criteria for each task
4. Files that will need modification
Output as structured task list compatible with ring:dev-cycle.
state_path = "docs/ring:dev-cycle/current-cycle.json"cycle_type = "prompt"source_prompt = "[user's prompt]"tasks array from ring:codebase-explorer outputAnti-Rationalization for Prompt-Only Mode:
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Skip codebase exploration, I understand the prompt" | Prompt understanding ≠ codebase understanding. Explorer provides context. | Always run ring:codebase-explorer |
| "Generate minimal tasks to go faster" | Minimal tasks = missed requirements. Comprehensive breakdown prevents rework. | Generate complete task breakdown |
| "User knows what they want, skip confirmation" | User intent ≠ generated tasks. Confirmation prevents wrong implementation. | Always confirm generated tasks |
Input: path/to/tasks.md or path/to/pre-dev/{feature}/ with optional second argument for custom instructions
Examples:
/ring:dev-cycle tasks.md/ring:dev-cycle tasks.md "Focus on error handling"docs/ring:dev-refactor/ → state_path = "docs/ring:dev-refactor/current-cycle.json", cycle_type = "refactor"state_path = "docs/ring:dev-cycle/current-cycle.json", cycle_type = "feature"custom_prompt field (empty string if not provided){state_path}, set indices to 0commit_timing field in statedocs/ring:dev-cycle/current-cycle.json firstdocs/ring:dev-refactor/current-cycle.json| Status | Action |
|---|---|
paused_for_approval | Re-present Step 11.1 checkpoint |
paused_for_testing | Ask if testing complete → continue or keep paused |
paused_for_task_approval | Re-present Step 11.2 checkpoint |
paused_for_integration_testing | Ask if integration testing complete |
paused (generic) | Ask user to confirm resume |
in_progress | Resume from current gate |
Task files are generated by /pre-dev-* or /ring:dev-refactor, which handle content validation. The ring:dev-cycle performs basic format checks:
| Check | Validation | Action |
|---|---|---|
| File exists | Task file path is readable | Error: abort |
| Task headers | At least one ## Task: found | Error: abort |
| Task ID format | ## Task: {ID} - {Title} | Warning: use line number as ID |
| Acceptance criteria | At least one - [ ] per task | Warning: task may fail validation gate |
MANDATORY: Scan the codebase once at cycle start to detect external dependencies. Store in state.detected_dependencies for use by Gates 2, 6, and 7.
detected_dependencies = []
1. Scan docker-compose.yml / docker-compose.yaml for service images:
- Grep tool: pattern "postgres" in docker-compose* files → add "postgres"
- Grep tool: pattern "mongo" in docker-compose* files → add "mongodb"
- Grep tool: pattern "valkey" in docker-compose* files → add "valkey"
- Grep tool: pattern "redis" in docker-compose* files → add "redis"
- Grep tool: pattern "rabbitmq" in docker-compose* files → add "rabbitmq"
2. Scan dependency manifests:
if language == "go":
- Grep tool: pattern "github.com/lib/pq" in go.mod → add "postgres"
- Grep tool: pattern "github.com/jackc/pgx" in go.mod → add "postgres"
- Grep tool: pattern "go.mongodb.org/mongo-driver" in go.mod → add "mongodb"
- Grep tool: pattern "github.com/redis/go-redis" in go.mod → add "redis"
- Grep tool: pattern "github.com/valkey-io/valkey-go" in go.mod → add "valkey"
- Grep tool: pattern "github.com/rabbitmq/amqp091-go" in go.mod → add "rabbitmq"
if language == "typescript":
- Grep tool: pattern "\"pg\"" in package.json → add "postgres"
- Grep tool: pattern "@prisma/client" in package.json → add "postgres"
- Grep tool: pattern "\"mongodb\"" in package.json → add "mongodb"
- Grep tool: pattern "\"mongoose\"" in package.json → add "mongodb"
- Grep tool: pattern "\"redis\"" in package.json → add "redis"
- Grep tool: pattern "\"ioredis\"" in package.json → add "redis"
- Grep tool: pattern "@valkey" in package.json → add "valkey"
- Grep tool: pattern "\"amqplib\"" in package.json → add "rabbitmq"
- Grep tool: pattern "amqp-connection-manager" in package.json → add "rabbitmq"
3. Deduplicate detected_dependencies
4. Store: state.detected_dependencies = detected_dependencies
5. Log: "Auto-detected external dependencies: [detected_dependencies]"
**MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]**
<auto_detect_reason> PM team task files often omit external_dependencies. If the codebase uses postgres, mongodb, valkey, or rabbitmq, these MUST be detected and passed to Gates 6 (integration) and 7 (chaos). Auto-detection at cycle level avoids redundant scans per gate. </auto_detect_reason>
REQUIRED SUB-SKILL: Use ring:dev-implementation
Execution Unit: Task (if no subtasks) or Subtask (if task has subtasks)
See shared-patterns/shared-orchestrator-principle.md for full details.
⛔ FORBIDDEN: Executing TDD-RED/GREEN logic directly from this step. MUST invoke the ring:dev-implementation skill via the Skill tool; it handles all TDD phases, agent selection, agent dispatch, standards verification, and fix iteration.
Gather from current execution unit:
implementation_input = {
// REQUIRED - from current execution unit
unit_id: state.current_unit.id,
requirements: state.current_unit.acceptance_criteria,
// REQUIRED - detected from project
language: state.current_unit.language, // "go" | "typescript" | "python"
service_type: state.current_unit.service_type, // "api" | "worker" | "batch" | "cli" | "frontend" | "bff"
// OPTIONAL - additional context
technical_design: state.current_unit.technical_design || null,
existing_patterns: state.current_unit.existing_patterns || [],
project_rules_path: "docs/PROJECT_RULES.md"
}
1. Record gate start timestamp
2. REQUIRED: Invoke ring:dev-implementation skill with structured input:
Skill("ring:dev-implementation") with input:
unit_id: implementation_input.unit_id
requirements: implementation_input.requirements
language: implementation_input.language
service_type: implementation_input.service_type
technical_design: implementation_input.technical_design
existing_patterns: implementation_input.existing_patterns
project_rules_path: implementation_input.project_rules_path
The skill handles:
- Selecting appropriate agent (Go/TS/Frontend based on language)
- TDD-RED phase (writing failing test, capturing failure output)
- TDD-GREEN phase (implementing code to pass test)
- Standards compliance verification (iteration loop, max 3 attempts)
- Re-dispatching agent for compliance fixes
- Outputting Standards Coverage Table with evidence
3. REQUIRED: Parse skill output for results:
Expected output sections:
- "## Implementation Summary" → status (PASS/FAIL), agent used
- "## TDD Results" → RED/GREEN phase status
- "## Files Changed" → created/modified files list
- "## Handoff to Next Gate" → ready_for_gate_1: YES/NO
if skill output contains "Status: PASS" and "Ready for Gate 1: YES":
→ Gate 0 PASSED. Proceed to Step 2.3.
if skill output contains "Status: FAIL" or "Ready for Gate 1: NO":
→ Gate 0 BLOCKED.
→ Skill already dispatched fixes to implementation agent
→ Skill already re-ran TDD and standards verification
→ If "ESCALATION" in output: STOP and report to user
4. **MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]**
5. When ring:dev-implementation skill returns PASS:
REQUIRED: Parse from skill output:
- agent_used: extract from "## Implementation Summary"
- tdd_red_status: extract from "## TDD Results" table
- tdd_green_status: extract from "## TDD Results" table
- files_changed: extract from "## Files Changed" table
- standards_compliance: extract from Standards Coverage Table
- agent_outputs.implementation = {
skill: "ring:dev-implementation",
agent: "[agent used by skill]",
output: "[full skill output]",
timestamp: "[ISO timestamp]",
duration_ms: [execution time],
tdd_red: {
status: "completed",
test_file: "[from skill output]",
failure_output: "[from skill output]"
},
tdd_green: {
status: "completed",
implementation_files: "[from skill output]",
pass_output: "[from skill output]"
},
standards_compliance: {
total_sections: [N from skill output],
compliant: [N sections with ✅],
not_applicable: [N sections with N/A],
non_compliant: 0
}
}
6. Display to user:
┌─────────────────────────────────────────────────┐
│ ✓ GATE 0 COMPLETE │
├─────────────────────────────────────────────────┤
│ Skill: ring:dev-implementation │
│ Agent: [agent_used] │
│ TDD-RED: FAIL captured ✓ │
│ TDD-GREEN: PASS verified ✓ │
│ STANDARDS: [N]/[N] sections compliant ✓ │
│ │
│ Proceeding to Gate 1 (DevOps)... │
└─────────────────────────────────────────────────┘
7. MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]
See "State Persistence Rule" section.
8. Proceed to Gate 1
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "I can run TDD-RED/GREEN directly from here" | Inline TDD = skipping the skill. Skill has iteration logic and validation. | Invoke Skill("ring:dev-implementation") |
| "I already know which agent to dispatch" | Agent selection is the SKILL's job, not the orchestrator's. | Invoke Skill("ring:dev-implementation") |
| "The TDD steps are documented here, I'll follow them" | These steps are REFERENCE, not EXECUTABLE. The skill is executable. | Invoke Skill("ring:dev-implementation") |
| "Skill adds overhead for simple tasks" | Overhead = compliance checks. Simple ≠ exempt. | Invoke Skill("ring:dev-implementation") |
| "I'll dispatch the agent and verify output myself" | Self-verification skips the skill's re-dispatch loop. | Invoke Skill("ring:dev-implementation") |
| "Agent already did TDD internally" | Internal ≠ verified by skill. Skill validates output structure. | Invoke Skill("ring:dev-implementation") |
REQUIRED SUB-SKILL: Use ring:dev-devops
Gate 1 is a BLOCKING gate. DevOps agent MUST create all required artifacts. If any artifact is missing:
See shared-patterns/standards-coverage-table.md → "ring:devops-engineer → devops.md" for all required sections.
Key artifacts from devops.md:
Gather from previous gates:
devops_input = {
// REQUIRED - from current execution unit
unit_id: state.current_unit.id,
// REQUIRED - from Gate 0 context
language: state.current_unit.language, // "go" | "typescript" | "python"
service_type: state.current_unit.service_type, // "api" | "worker" | "batch" | "cli"
implementation_files: agent_outputs.implementation.files_changed, // list of files from Gate 0
// OPTIONAL - additional context
gate0_handoff: agent_outputs.implementation, // full Gate 0 output