> ## Documentation Index
> Fetch the complete documentation index at: https://evoke-f0bfabff.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi Tools Reference

> Complete reference for all native Pi SDLC tools exposed by the RStack extension.

## 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.

```text theme={null}
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.

```text theme={null}
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:**

```text theme={null}
.rstack/runs/<run_id>/
  manifest.json
  context.md
```

***

### `sdlc_clarify`

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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
sdlc_plan()
```

**Creates:**

```text theme={null}
.rstack/runs/<run_id>/
  plan.md
  tasks.json
  traceability.json
  specs/
    product-brief.md
    requirements.json
    architecture.md
```

<Warning>
  `sdlc_plan` requires approval before `sdlc_build_next` can be called.
</Warning>

***

### `sdlc_spec`

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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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`.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
# 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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.