Skip to main content
This guide walks through a complete RStack run using the Pi native adapter. The same lifecycle applies to all adapters — only the tool invocation syntax differs.

​
1. Load the orchestrator

Start every run by loading the RStack orchestrator for your goal: 
sdlc_orchestrate(goal="Build a production-ready REST API with authentication and tests")
This injects the orchestrator, builder, and validator operating instructions so the agent knows how to behave throughout the lifecycle.

​
2. Start a run

sdlc_start(goal="Build a production-ready REST API with authentication and tests")
RStack creates a new run directory: 
.rstack/runs/
  run_20240525_001/
    manifest.json         ← run metadata
    context.md            ← goal and environment context

​
3. Clarify requirements

If the goal is ambiguous, RStack asks product-owner questions: 
sdlc_clarify()
This captures decisions like:
  • Which framework? (Express, Fastify, etc.)
  • Which database?
  • What auth strategy? (JWT, OAuth, etc.)
  • Target deployment environment?

​
4. Plan

sdlc_plan()
RStack generates: 
.rstack/runs/run_20240525_001/
  plan.md                 ← delivery plan
  tasks.json              ← task breakdown with acceptance criteria
  specs/
    product-brief.md
    requirements.json
    architecture.md
  traceability.json

​
5. Review and approve

Review the generated specs, then record your human approval gates: 
sdlc_approve(artifact="plan.md", status="APPROVED")
sdlc_approve(artifact="requirements.json", status="APPROVED")
sdlc_approve(artifact="architecture.md", status="APPROVED")
RStack will not execute implementation tasks until plan and requirements are approved in interactive mode. This is intentional — it keeps you as the product owner.

​
6. Check available agents

sdlc_agents()
This lists the packaged and project-local agents, skills, and plugins that will be used for your run.

​
7. Build

Repeatedly call sdlc_build_next to execute tasks one at a time: 
sdlc_build_next()
Each call:
  1. Selects the next pending task
  2. Assembles a task packet with the right agents, skills, and plugins
  3. Executes using the builder team
  4. Writes builder.json as a contract

​
8. Validate

After each build step, validate the output: 
sdlc_validate()
The validator team (read-only tools by default) checks:
  • Does output meet acceptance criteria?
  • Are tests passing?
  • Is security review satisfied?
Writes validation.json to the task directory.

​
9. Check status

At any point: 
sdlc_status()
Returns a dashboard of:
  • Completed vs pending tasks
  • Missing approval gates
  • Registry counts
  • Next recommended action

​
10. Save learnings

At the end of every run: 
sdlc_memory()
Appends key learnings to .rstack/memory/learnings.jsonl for use in future runs.

​
Run state layout

After a complete run, your .rstack/ looks like: 
.rstack/
  memory/
    learnings.jsonl
  registry/
    registry.json
    agents.json
    skills.json
    plugins.json
    routing.json
  runs/
    run_20240525_001/
      manifest.json
      context.md
      plan.md
      tasks.json
      approvals.json
      traceability.json
      events.jsonl
      specs/
        product-brief.md
        requirements.json
        architecture.md
        implementation-report.json
        qa-report.json
        security-review.md
        handoff.md
        release-readiness.json
      tasks/
        task_001/
          prompt.md
          builder.json
          validation.json
        task_002/
          ...
Every artifact is inspectable, versioned with the run, and traceable from requirements to evidence.