[codex] Document runtime invocation surfaces

[richard-devbot]

Closes #111

Summary

• Document Pi vs Claude Code vs CLI runtime differences.
• Document exact agent invocation model and enforcement boundaries.
• Add missing Pi decision/readiness tool references.
• Align public and Mintlify integration docs.

Validation

• node --test tests/validate-references.test.js
• node bin/rstack-agents.js validate

Summary by CodeRabbit

• Documentation
  • Updated Claude Code integration documentation with clearer runtime surfaces and limitations.
  • Expanded Pi integration tool capabilities and slash-command documentation.
  • Enhanced Claude Code adapter documentation with detailed invocation workflow.
  • Updated Pi tools reference with expanded parameters for clarification requests.
  • Clarified Pi extension lifecycle flow including decision and readiness checks.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
evoke-f0bfabff	🟢 Ready	View Preview	Jun 20, 2026, 2:42 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a5f68d7-75e4-43de-9ade-d4f904f2e74a

📥 Commits

Reviewing files that changed from the base of the PR and between 4108981 and ef3abb4.

📒 Files selected for processing (5)

• docs/integrations/claude-code.md
• docs/integrations/pi.md
• docs/mintlify/adapters/claude-code.mdx
• docs/mintlify/reference/pi-tools.mdx
• docs/public/pi-extension.md

---

📝 Walkthrough

Walkthrough

Documentation updates across five files clarify RStack's runtime surface differences between Pi extension, Claude Code, and CLI. Changes add new SDLC tools (sdlc_decisions, sdlc_dor_check, sdlc_memory, sdlc_trace, sdlc_rollback) to reference tables, document sdlc_clarify's new answers/run_id parameters, and replace Claude Code's plugin-based description with a portable-asset invocation model that explicitly states its lack of Pi-native tool_call gating.

Changes

Runtime Differences: Pi vs Claude Code Documentation

Layer / File(s)	Summary
sdlc_clarify parameter docs and Pi tool flow routing docs/mintlify/reference/pi-tools.mdx, docs/public/pi-extension.md	sdlc_clarify reference now shows answers=[...] call form with an optional run_id parameter table. The Pi tool flow inserts sdlc_decisions/sdlc_decide and sdlc_dor_check as a required routing stage between sdlc_clarify and sdlc_plan.
Pi runtime surfaces, tool table, and recommended use lifecycle docs/public/pi-extension.md, docs/integrations/pi.md	Pi runtime entry points table expanded with sdlc_trace/sdlc_rollback and sdlc_memory. Pi integration's sdlc_* tool table and slash-command set updated with new tools including orchestration, decisions, DOR checking, and dashboard. Recommended use lifecycle adds an explicit step 4 for human decision readiness.
Claude Code invocation model and tool_call gating limitations docs/integrations/claude-code.md, docs/mintlify/adapters/claude-code.mdx	Replaces the prior plugin/SDLC command description with a portable-asset execution model. Adds a runtime surfaces table (CLAUDE.md/SOUL/HEARTBEAT, agent/skill/plugin assets, rstack-agents CLI bridge). Explicitly documents that Claude Code does not provide Pi-native tool_call gating and cannot intercept destructive tool calls.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• richard-devbot/SDLC-rstack#122: Updates the same docs/mintlify/adapters/claude-code.mdx file to describe Claude Code invocation via portable project assets and rstack-agents init bootstrap templates rather than Pi lifecycle hooks, directly overlapping with this PR's Claude Code adapter section.

Poem

🐇 Hop hop through the docs so clear,
Pi hooks and Claude Code paths appear,
sdlc_clarify answers the call,
Decisions and DOR checks stand tall,
Tool gating notes keep the flow true —
A rabbit-approved runtime review! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] Document runtime invocation surfaces' clearly and concisely summarizes the main change: documenting how runtime environments invoke SDLC-rstack surfaces.
Linked Issues check	✅ Passed	The PR fully satisfies all acceptance criteria from issue #111: documentation clearly distinguishes Pi lifecycle hooks vs. Claude Code assets vs. CLI commands, documents runtime-specific tool availability and enforcement boundaries including destructive-action gates, and maps agents to file paths.
Out of Scope Changes check	✅ Passed	All changes directly support the stated objective of documenting runtime invocation surfaces across Pi, Claude Code, and CLI. Documentation updates to five files clarify invocation patterns and enforcement boundaries without introducing unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ble-0-runtime-docs-111

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →