Pi Tools Reference - RStack SDLC

Tool surface

The RStack Pi extension registers these tools on session_start. They are available in any Pi session where RStack is installed.

`sdlc_orchestrate`

Load the RStack orchestrator, builder, and validator operating instructions for a goal. Call first — before sdlc_start. Injects the core agent instructions into the session.

sdlc_orchestrate(goal="Build a production-ready REST API with auth and tests")

Parameter	Type	Required	Description
`goal`	string	✅	The high-level delivery goal

`sdlc_start`

Create a new run directory under .rstack/runs/<run_id>/ and initialize run state.

sdlc_start(goal="Build a production-ready REST API with auth and tests")

Parameter	Type	Required	Description
`goal`	string	✅	The delivery goal (same as `sdlc_orchestrate`)

Creates:

.rstack/runs/<run_id>/
  manifest.json
  context.md

`sdlc_clarify`

Ask or capture product-owner answers before planning. Called when the goal has ambiguities.

sdlc_clarify()
sdlc_clarify(answers=["Ship password login only for v1", "Use Postgres because the repo already has it"])

RStack surfaces open_questions from the transcript and waits for your answers before proceeding to sdlc_plan.

Parameter	Type	Required	Description
`run_id`	string	—	Target a specific run (default: latest active run)
`answers`	string[]	—	Product-owner answers or decisions to append to `context.md`

`sdlc_decisions`

List the Decision Queue, or add a pending run-level decision that must be resolved before a later stage.

sdlc_decisions()
sdlc_decisions(
  question="Should refresh tokens be stored in Redis or Postgres?",
  impact="architecture",
  required_before_stage="06-architecture",
  owner="product-owner"
)

Parameter	Type	Required	Description
`run_id`	string	—	Target a specific run (default: latest active run)
`question`	string	—	Add this question as a pending decision
`impact`	`"architecture"` \| `"security"` \| `"budget"` \| `"scope"` \| `"delivery"`	—	Decision category, defaults to `scope`
`required_before_stage`	string	—	Canonical stage that must not proceed until the decision is resolved
`recommendation`	string	—	Suggested answer or tradeoff note
`owner`	string	—	Human or role responsible for resolving the decision

Writes decision state under the active run and appends a decision_added event when a new question is created.

`sdlc_decide`

Resolve or waive a pending Decision Queue item.

sdlc_decide(
  decision_id="decision_001",
  status="resolved",
  resolution="Use Redis for refresh-token rotation; Postgres remains the source of user identity."
)

Parameter	Type	Required	Description
`run_id`	string	—	Target a specific run (default: latest active run)
`decision_id`	string	✅	Decision Queue item to resolve or waive
`status`	`"resolved"` \| `"waived"`	—	Final decision status, defaults to `resolved`
`resolution`	string	✅	Human-readable resolution or waiver reason
`resolved_by`	string	—	Resolver identity (defaults to the detected user identity)

Writes the decision update, appends a decision_resolved event, and records traceability for the decision.

`sdlc_dor_check`

Run the Definition-of-Ready gate for a target stage. This checks unresolved decisions and writes readiness reports before builders are allowed to advance.

sdlc_dor_check()
sdlc_dor_check(target_stage="07-code")

Parameter	Type	Required	Description
`run_id`	string	—	Target a specific run (default: latest active run)
`target_stage`	string	—	Canonical stage to check readiness for, defaults to `07-code`

Creates or updates readiness artifacts for the run and appends a dor_check event to events.jsonl.

`sdlc_plan`

Generate the delivery plan, task breakdown, spec artifacts, and traceability.

sdlc_plan()

Creates:

.rstack/runs/<run_id>/
  plan.md
  tasks.json
  traceability.json
  specs/
    product-brief.md
    requirements.json
    architecture.md

sdlc_plan requires approval before sdlc_build_next can be called.

`sdlc_spec`

Read or update governed spec artifacts under .rstack/runs/<run_id>/specs/.

sdlc_spec(artifact="requirements.json")
sdlc_spec(artifact="architecture.md", update="Add Redis caching layer for session storage")

Parameter	Type	Required	Description
`artifact`	string	✅	Spec file name (e.g. `architecture.md`)
`update`	string	—	Instruction for updating the spec

`sdlc_approve`

Record a human approval or rejection gate. Required before build and release phases.

sdlc_approve(artifact="plan.md", status="APPROVED")
sdlc_approve(artifact="requirements.json", status="APPROVED")
sdlc_approve(artifact="architecture.md", status="APPROVED")
sdlc_approve(artifact="release-readiness.json", status="APPROVED")
sdlc_approve(artifact="destructive-action", status="APPROVED")

Parameter	Type	Required	Description
`artifact`	string	✅	The artifact or action being approved
`status`	`"APPROVED"` \| `"REJECTED"`	✅	Your decision
`notes`	string	—	Optional notes or conditions

Writes to .rstack/runs/<run_id>/approvals.json.

`sdlc_agents`

List all available agents, skills, and plugins for the current run.

sdlc_agents()
sdlc_agents(domain="backend")
sdlc_agents(kind="specialist")

Parameter	Type	Required	Description
`domain`	string	—	Filter by domain (e.g. `backend`, `frontend`)
`kind`	string	—	Filter by kind (`core`, `sdlc`, `specialist`, `plugin`)

`sdlc_delegate`

Spawn an isolated Pi worker agent for a bounded task. Validators default to read-only tools.

sdlc_delegate(role="builder", task="Implement JWT auth middleware")
sdlc_delegate(role="validator", task="Review auth implementation for security issues")
sdlc_delegate(role="researcher", task="Find best practices for refresh token storage")

Parameter	Type	Required	Description
`role`	`"builder"` \| `"validator"` \| `"researcher"` \| `"reviewer"`	✅	Worker role
`task`	string	✅	Task description
`tools`	string[]	—	Override default tool set
`context`	string	—	Additional context to pass to the worker

`sdlc_build_next`

Prepare the next pending task packet with core, SDLC, specialist, skill, and plugin context. Requires plan approval.

sdlc_build_next()
sdlc_build_next(task_id="task_003")

Parameter	Type	Required	Description
`task_id`	string	—	Target a specific task (default: next pending)

Returns a task packet ready for execution. After completing the task, write builder.json.

`sdlc_validate`

Run the validator team against the most recently completed builder task. Writes validation.json.

sdlc_validate()
sdlc_validate(task_id="task_003")

Parameter	Type	Required	Description
`task_id`	string	—	Target a specific task (default: most recent)

`sdlc_status`

Show run status, task progress, missing approvals, registry counts, and next recommended action.

sdlc_status()

Example output:

Run: run_20240525_001
Goal: Build a production-ready REST API

Tasks:   6/10 complete (4 pending)
Pending approvals: release-readiness.json

Registry: 196 agents · 156 skills · 72 plugins
Next: sdlc_build_next() → task_007 (Add rate limiting middleware)

`sdlc_memory`

Search or append project learnings for future runs.

# Search existing learnings
sdlc_memory(search="JWT refresh token")

# Append a new learning
sdlc_memory(append="Always validate tenant_id in JWT before any data access")

Parameter	Type	Required	Description
`search`	string	—	Search query for existing learnings
`append`	string	—	New learning to save

Writes to .rstack/memory/learnings.jsonl.

`sdlc_dashboard`

Launch the live HTML Observability Hub for the current run. Generates dashboard.html and starts a local HTTP server.

sdlc_dashboard()
sdlc_dashboard(run_id="2024-05-25T10-00-00Z-my-run")

Parameter	Type	Required	Description
`run_id`	string	—	Target a specific run (default: most recent)

The dashboard auto-refreshes every 2 seconds and shows:

Stage Execution Timeline — all 15 canonical stages with status pills (READY / PENDING / PASS / FAIL)
Cumulative Metrics — total duration, API cost cap ($), tool-call buffer (current / 40)
Traceability Explorer — link to traceability.json
Harness Guardrail Limits — enforced policy values

Writes dashboard.html to .rstack/runs/<run_id>/dashboard.html and serves it at http://localhost:3008 (port configurable).

`sdlc_trace`

Print a chronological event trace for the current or specified task. Includes tool calls, guardrail hits, memory events, and validation check results.

sdlc_trace()
sdlc_trace(task_id="003-architecture")

Parameter	Type	Required	Description
`task_id`	string	—	Target a specific task (default: most recent)

Example output:

[10:01:05] run_started          → goal: "Build a weather app"
[10:01:06] builder_task_prepared → task: 003-architecture
[10:01:07] tool_call             → read: src/index.js
[10:01:08] guardrail_triggered   → maxToolCallsPerTask approaching (38/40)
[10:01:09] task_validated        → PASS
[10:01:09] episode_memory_written → episode_abc123

`sdlc_rollback`

Restore a stage directory to its last saved checkpoint snapshot.

sdlc_rollback(stage_id="06-architecture")
sdlc_rollback(stage_id="03-documentation", run_id="2024-05-25T10-00-00Z-my-run")

Parameter	Type	Required	Description
`stage_id`	string	✅	Stage to restore (e.g. `06-architecture`)
`run_id`	string	—	Target a specific run (default: most recent)

Checkpoints are created automatically after each successful sdlc_validate. Rollback copies the checkpoint back over the live stage directory and appends a stage_checkpoint_reverted event to events.jsonl. Returns NO_CHECKPOINT if no snapshot exists for the stage.

​Tool surface

​sdlc_orchestrate

​sdlc_start

​sdlc_clarify

​sdlc_decisions

​sdlc_decide

​sdlc_dor_check

​sdlc_plan

​sdlc_spec

​sdlc_approve

​sdlc_agents

​sdlc_delegate

​sdlc_build_next

​sdlc_validate

​sdlc_status

​sdlc_memory

​sdlc_dashboard

​sdlc_trace

​sdlc_rollback

Tool surface

`sdlc_orchestrate`

`sdlc_start`

`sdlc_clarify`

`sdlc_decisions`

`sdlc_decide`

`sdlc_dor_check`

`sdlc_plan`

`sdlc_spec`

`sdlc_approve`

`sdlc_agents`

`sdlc_delegate`

`sdlc_build_next`

`sdlc_validate`

`sdlc_status`

`sdlc_memory`

`sdlc_dashboard`

`sdlc_trace`

`sdlc_rollback`