RSDC v4.0: Recursive Specs-Driven Coding Framework

**See video summary of RSDC 4.0 **

The "State-Aware" Edition with Transactional Rollbacks

RSDC v4.0 is an autonomous engineering framework designed to transform Large Language Models (LLMs) from "Black Box" code generators into transparent, self-correcting engineering teams. It merges [...]

**It forces AI models to stop "just writing code" and instead act as a coordinated team that defines the ** "Soul" (Vibe) **, the ** "Brain" (Logic) **, and the **"Memory" (Traceability) o[...]

**

**

🧠 Core Philosophy: The "Glass Box" Protocol

**Unlike standard agent frameworks, RSDC v4.0 enforces ** 100% Traceability **. Agents are forbidden from making silent decisions. Alongside the code, the system generates a complete audit trail o[...]

Key Upgrades in v4.0

**1. **Transactional State (Saga Protocol): The system now maintains a persistent global state (00_project_state.md) to survive context window clears and enforce "Rollback" protocols if a task w[...]

**2. **Wave-Based Parallelism: Tasks are no longer linear lists but dependency-aware "Waves" (e.g., Database Schema must clear before API Endpoints begin).

**3. **Self-Annealing Rules: If a tool fails, the agent doesn't just fix the code; it updates the instruction set (00_tech_stack_rules.md) to prevent future agents from making the same mistake.

**4. **Goal-Backward Verification: A new "Auditor" agent (Stage 6) validates the product against user goals, not just unit tests.

**

**

🔄 The 6-Stage Pipeline (State-Aware)

| Stage | Role | Input | Output Artifact | Key Behavior [...] | --------------- | ------------------------- | -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------[...] | 1 | Architect | User Query | 00_tech_stack_rules.md | **Skill Loading:Defines strict "Context Packing" rules (e.g., "Use HTML5 Canvas").****Self-Annealing:**Updates rul[...] | 2 | Product Manager | Tech Rules | 02_pm_prd.md | Vibe Spec:Defines Visual Personality (e.g., "Neon Cyber-Organic") & Motion. [...] | 3 | Tech Lead | PRD | 03_gherkin_specs.feature | **Data Lockdown:**Defines strict JSON Schemas alongside Logic Specs to prevent Frontend/Backend drift. [...] | 4 | Eng. Manager | Specs | 04_task_waves.md | **Wave Scheduling:**Groups tasks by dependency (Wave 1: Core, Wave 2: API).**Link Handshake:**Verifies environment/API[...] | 5 | Developer | Task Waves | 06_verification_logs.md | **Saga Execution:**Atomic coding with rollback capabilities. Updates 00_project_state.mdafter every commit. [...] | 6 | Auditor | PRD + App | 07_final_audit.md | **Goal Verification:**Validates "Must Haves" from the PRD against the final build (User Acceptance Testing). [...]

**

**

📂 Directory Structure & Artifacts

**To enable **Context Isolation and Directory Hygiene , the framework uses two distinct folders:

**1. **/artifacts/ (The "Source of Truth")

**• **00_project_state.md (NEW) : The persistent memory of the current Phase, Wave, and Failed Attempts (SagaLLM).

• 00_decision_journal.md: High-level reasoning log (e.g., "Why we chose Canvas over DOM").

**• **00_tech_stack_rules.md: The rulebook that evolves via Self-Annealing.

• 05_dev_decision_trace.md: Low-level logic trace (e.g., "Why we used requestAnimationFrame").

**2. **/.tmp/ (The Workspace)

**• **Used for raw API responses, debug logs, and intermediate file processing.

**• **Rule: Never committed to the final repository.

**

**

🛡️ Operational Boundaries (The 3-Tier System)

RSDC v4.0 replaces binary constraints with a nuanced safety protocol:

**• **✅ Always (Autonomous): Reading files, running tests, writing to .tmp, reading /artifacts/.

**• **⚠️ Ask First (Human Gate): Deleting files, installing new packages, committing to main.

• 🚫 Never (Hard Stop): Hardcoding secrets (use .env), modifying code outside the active Task ID.

**

**

🚀 Usage

1. Install: Place core files (system_prompt.md, agent-orchestration.md) in .cursor/rules or project root.

**2. **Initialize: Create empty /artifacts/ and /.tmp/ folders.

**3. **Trigger:

• "Use @system_prompt.md to create a [Your Project Idea] [Flag]"

Step-by-Step Breakdown

**1. ** Reference the Brain ( @system_prompt.md **):**You must type @system_prompt.md (or whatever you named the core file) and select it from the dropdown. This forces the LLM to read the [...]

**2. ****Define the Project:**Replace [Your Project Idea] with your request.

** ◦ **Example:"Use @system_prompt.md to create a 'Budget Tracker App'..."

** ◦ **Example:"Use @system_prompt.md to create an 'In-browser 1st person shooter game'..."

**3. **Choose Your Approval Mode (The Flag):You must append one of the following flags to tell the "Recursive Pipeline Orchestrator" how to handle state transitions:

** ◦ ** -stagedapprovals **: ****(Recommended)**The system will pause after every stage (e.g., after the PM creates the PRD) and ask for your permission to proceed. This allows you to review [...]

** ◦ ** -autoapproval **:**The system attempts to run the entire 6-stage pipeline (Architect → Auditor) in one continuous flow without pausing. This is faster but riskier if the "Vibe" [...]

**

**

❓ FAQ

❓Q: How does the 'Saga Protocol' fix infinite loops?**A: If a verification step fails twice, the system triggers "Localized Re-Reasoning".

If a Wave fails 3 times, the **Saga Protocol triggers a "Rollback," reverts the git changes, and summons the Architect to re-plan, rather than blindly retrying.

❓Q: How do Wave Scheduling and Saga Protocol work together?

Based on our conversation history regarding RSDC v4.0 and the provided sources, Wave Scheduling and the Saga Protocol work together to transform code generation from a fragile linear process i[...]

While Wave Scheduling organizes execution (parallelism and dependencies), the Saga Protocol manages state and recovery (persistence and rollbacks). They integrate through the following fou[...]

1. The Transactional Boundary (Waves as Checkpoints)

In the RSDC v4.0 architecture, a "Wave" acts as a single atomic transaction. The Saga Protocol uses the start and end of a Wave as strict checkpoints for the Global State.

• Wave Scheduling: The Engineering Manager groups tasks into dependent clusters in 04_task_waves.md (e.g., Wave 1: Database must finish before Wave 2: API starts).
• Saga Protocol: Before Wave $N$ begins, the system records the current "clean" state in 00_project_state.md. This creates a restore point.

2. Execution & Verification (The "Try" Block)

Once a Wave begins, the Developer agent attempts to complete the assigned tasks.

• Wave Execution: Agents execute tasks within the current wave, often in parallel.
• Verification: Upon completion, the system checks the "Verification Conditions" (defined in Stage 4) to prove functionality (e.g., "Console logs show steady 60fps").
• Saga Tracking: As individual tasks pass verification, they are logged in the 00_project_state.md file as "Pending Commit."

3. The Failure Loop (Localized vs. Systemic)

If verification fails (e.g., the snake moves through walls), the two systems collaborate to handle the error:

• Level 1: Localized Re-Reasoning (RSDC Standard): If a specific task fails, the system triggers "Localized Re-Reasoning," prompting the Developer to fix that specific module without restarting th[...]
• Level 2: Saga Escalation: If the fix fails verification again, the Saga Protocol increments a "Failed Attempts" counter in the global state file. It tracks how many times this specific Wav[...]

4. The Rollback (Compensating Transaction)

This is the critical intersection where the Saga Protocol protects the codebase from "death spirals."

• Trigger: If the "Failed Attempts" counter hits the limit (e.g., 3 failures), the Saga Protocol declares the Wave a total failure.
• Rollback Action: Instead of allowing the agent to continue adding bad code, the system triggers a Compensating Transaction . It reverts the git repository to the "clean state" recorded befo[...]
• Escalation: The system marks the Wave as FAILED in 00_project_state.md and summons the Architect to re-plan the approach, ensuring the project does not proceed on a broken foundation.

Summary of Integration

Feature	Role in Workflow	Synergy
Wave Scheduling	DefinesDependency Groups(What runs together).	prevents "API" tasks from starting before "Database" tasks fail or succeed.
Saga Protocol	DefinesState Persistence(Memory).	Ensures that if Wave 2 crashes, we don't lose the successful work from Wave 1.
Verification	DefinesTruth Conditions(Success Criteria).	Acts as the "Commit Gate" for the Saga transaction.
Rollback	DefinesRecovery(Undo Button).	Allows the system to "cleanly fail" a Wave without polluting the codebase.

❓Q: How do verification logs ensure the game works?**A: In 04_task_waves.md, the Manager assigns "Truth Conditions" (e.g., "Console logs show steady 60fps").

The Developer must generate a "Proof of Work" in 06_verification_logs.md before the Wave is marked complete.**

**Q: Which ADK version is this?**A: This is the Hybrid Simulation (Version B) **. It simulates the Google ADK's **RecursivePipelineOrchestrator and output_schema using Markdown contracts [...]

❓Q:Tell me more about the new Auditor role in Stage 6.

Stage 6: The Auditor is a newly introduced "User Acceptance Testing" (UAT) agent designed to bridge the gap between technical correctness and product fulfillment .

While Stage 5 (Developer) proves that the code runs without errors, Stage 6 proves that the software actually meets the human user's intent.

1. Core Purpose: "Goal-Backward" Verification

**In the standard RSDC v3.0 pipeline, verification is ** technical . The Engineering Manager (Stage 4) defines conditions like "Console logs show steady 60fps".**The Auditor (Stage 6) shifts t[...]

2. Operational Workflow

The Auditor does not look at code syntax. Instead, it acts as a proxy for the human client.

**• **Inputs:

** ◦ ** /artifacts/02_pm_prd.md : It reads the "Source of Truth" for the product vision.

** ◦ ** /artifacts/00_project_state.md : It checks the transactional history (Saga Protocol) to see known failure points.

**• **Process (The Interrogation):

** 1. **Extraction: It extracts every "Must Have" feature and "Vibe Spec" from the PRD.

** 2. Question Generation: It converts requirements into specific "User Journey" questions (e.g., Requirement: "Neon Cyber-Organic Vibe"→Audit Question: "Do the UI elements possess [...]

** 3. **Evidence Demand: It challenges the system to provide a screenshot or terminal output specifically proving that journey.

**• **Output:

** ◦ ** /artifacts/07_final_audit.md : A final report card grading the release.

3. The "Three-Tier" Audit

The Auditor evaluates the software across the three dimensions defined in the RSDC "Glass Box" philosophy:

| Dimension | Source Artifact | Auditor's Check [...] | ------------------------------ | ------------------------------- | -----------------------------------------------------------------------------------------------------------------------------------[...] | The "Soul" (Vibe) | 02_pm_prd.md | **Visual Compliance:**Does the app strictly adhere to the "Visual Personality" (e.g., HSL dynamic shifts, rounded corners) defined by the P[...] | The "Brain" (Logic) | 03_tl_gherkin_specs.feature | **Feature Completeness:**It verifies "Truth Conditions" not via unit tests, but via simulated user actions (e.g., "If I crash into a wall, [...] | The "Memory" (Trace) | 00_decision_journal.md | **Compliance Check:It ensures no "Shadow Logic" exists. If a feature is in the app but not in the Decision Journal, the Auditor flags i[...]

4. Integration with the Saga Protocol

**As discussed in the v4.0 upgrade, the Auditor serves as the **Final Commit Gate for the project.

**• **If the Auditor marks /artifacts/07_final_audit.md as FAILED : The Saga Protocol triggers a "Rollback" or summons the Architect (Stage 1) to re-plan the missing features.

**• **If PASSED : The code is deemed ready for the human user to deploy.

This role prevents the common agentic failure mode where an AI writes perfect, bug-free code that does absolutely nothing the user asked for.

❓Q:What happens to the decision journal during a Saga rollback?

**Based on the Saga Protocol (detailed in our conversation history) and the Glass Box Protocol (Source), the **Decision Journal (/artifacts/00_decision_journal.md) is treated differe[...]

**While the code is reverted to a previous state, the Decision Journal is ** preserved and annotated **. It acts as a "Black Box Flight Recorder" that must survive the crash to prevent history fro[...]

Here is the specific workflow for the Decision Journal during a Saga Rollback:

1. Persistence vs. Reversion

**• **The Code (Git Revert): The actual application code and file structure are strictly rolled back to the "clean state" recorded in 00_project_state.md to undo the damage.

**• **The Journal (Immutable History): The entries in 00_decision_journal.md corresponding to the failed attempt are NOT deleted **. Deleting them would violate the "100% Traceability" ma[...]

2. The "Compensating Entry"

**When a rollback is triggered (after 3 failed verification attempts), the system appends a **Compensating Transaction entry to the journal. This entry effectively "closes" the failed branch of re[...]

**• **Format: The Agent writes a "Post-Mortem" entry immediately following the failed logic.

**• **Example Journal Entry:

3. Support for "Self-Annealing"

**Preserving the Decision Journal is critical for the **Self-Annealing mechanism (discussed in our conversation history).

**• **If the journal were rolled back, the Architect (Stage 1) would lose the context of why the previous attempt failed.

**• **By reading the "Compensating Entry" in the preserved journal, the Architect can update the 00_tech_stack_rules.md (e.g., adding "Rule: ALWAYS use Axios with Proxy") to ensure the next agent [...]

4. Integration with Global State

**The Journal works in tandem with the **00_project_state.md file introduced in RSDC v4.0.

**• ** 00_project_state.md **: Tracks the **counter (e.g., "Failed Attempts: 3").

**• ** 00_decision_journal.md **: Tracks the **qualitative reason (e.g., "We chose the wrong library").

**In summary, during a rollback, the Decision Journal serves as the ** memory of the failure **, ensuring that while the code is reset, the **wisdom gained from the error is retained.

❓Q:What specific data does the Saga Protocol preserve for recovery?

**Based on the **RSDC v4.0 upgrade detailed in our conversation history and the Glass Box Protocol defined in the sources, the Saga Protocol preserves two distinct categories of data during re[...]

Here is the specific data preserved:

1. Transactional State Data (The "Pointer")

**To prevent the agent from getting lost after a context window clear or a crash, the Saga Protocol persists a structured snapshot in ** /artifacts/00_project_state.md **. This file acts similarly[...]

Specific data points preserved include:

**• **Current Phase & Wave: The exact position in the execution pipeline (e.g., "Phase: Execution, Wave: 2 - API Integration") to ensure the agent resumes exactly where it left off.

**• **The "Clean State" ID: A reference (typically a Git commit hash) to the last successful "Wave" completion. This marks the safe point for a Rollback if the current attempt fails.

**• **Failure Counter: An integer tracking how many times the current Wave has failed verification (e.g., failed_attempts: 2). If this hits the limit (3), it triggers the Rollback Protocol.

**• **Task Completion Register: A list of Task IDs (e.g., ["task_1.1", "task_1.2"]) that have passed verification, ensuring the agent does not redundantly re-attempt successful work.

2. Reasoning State Data (The "Black Box Recorder")

**While the code itself is reverted during a rollback, the **Decision Journal is strictly preserved. This aligns with the RSDC "Glass Box" philosophy, which mandates a "complete audit trail of Why[...]

**Specific data preserved in **/artifacts/00_decision_journal.md includes:

**• **The Failed Logic: The reasoning that led to the error is kept as a "Post-Mortem" entry.

**• **The Compensating Transaction: A specific log entry detailing why the rollback occurred (e.g., "Action: Reverting. Reason: CORS errors caused by fetch()").

• Strategic Context: High-level architectural choices (e.g., "Selected HTML5 Canvas") remain available so the Architect does not re-litigate settled decisions.

3. Implementation Context

**In the core architecture, this preservation simulates the ****Google ADK ** SessionService , which uses a database or in-memory storage to persist state dictionaries. In the "Hybrid" file-ba[...]

**Summary of Recovery Action:**When a recovery is triggered, the system reads 00_project_state.md to reset the workflow pointer, reverts the code to the "Clean State," but appends to `00[...]

❓Q: Can the Saga Protocol handle multiple concurrent feature branches?

**Based on the **Saga Protocol and Wave Scheduling architecture defined in our conversation history, the answer is No, not in the traditional sense.

**The Saga Protocol is designed to manage **Task Parallelism (executing multiple tasks within the same context), not Branch Parallelism (managing divergent, competing feature sets simultaneous[...]

Here is the detailed technical breakdown of why the protocol enforces linearity, and how it handles concurrency within those constraints:

1. The Singleton State Bottleneck

**The core limitation lies in the **Global State File (/artifacts/00_project_state.md) introduced in RSDC v4.0.

**• **The Mechanism: The Saga Protocol relies on this file to track the Current Phase, Current Wave, and the specific Clean State ID (Git Commit Hash) for rollbacks.

**• **The Conflict: If you attempted to run two concurrent feature branches (e.g., "Feature A" and "Feature B"), both agents would attempt to write to the single 00_project_state.md file. Agen[...]

**• **Conclusion: The Saga Protocol enforces a Single-Threaded Orchestration layer over a Multi-Threaded Execution layer.

2. Concurrency is Handled via "Waves"

**While the protocol cannot handle divergent feature branches, it **does handle concurrent work through Wave Scheduling (defined in our previous turn).

**• **Intra-Wave Concurrency: Inside a single Wave (e.g., Wave 1), multiple tasks (Task 1.1, Task 1.2) act like temporary concurrent branches.

**• **The Synchronization Gate: The Saga Protocol forces a "Join" operation at the end of the Wave. All tasks in Wave 1 must pass the Verification Conditions before the protocol updates the [...]

3. The "Subtree Repair" Exception

The only time the protocol creates a temporary, isolated branch is during "Localized Re-Reasoning" (Source).

• **Scenario: If a specific task fails verification (e.g., "Snake moves through walls"), the system triggers a "Subtree Repair."**

**• **Behavior: The protocol isolates this specific task. The Developer creates a temporary fix (effectively a hotfix branch).

**• **Resolution: This branch must be immediately merged or discarded. The Saga Protocol will not allow the pipeline to proceed to the next Wave until this "Subtree" is resolved and the Global S[...]

Summary: How RSDC v4.0 manages Git

**• **Standard Git Flow: Parallel Feature Branches → Merge Conflicts → Resolution.

• RSDC Saga Flow: Wave 1 (Parallel Tasks) **→**Strict Verification Gate→** Global State Commit → Wave 2.**

**The system trades the flexibility of long-lived feature branches for the ** safety of transactional rollbacks , ensuring that the project never advances on a broken foundation.