Skip to content

Commit 9e63a88

Browse files
tcballardtcballard
authored
feat(guide): RAC Guide MCP server, onboarding, and grounding demo [roadmap:v0.10.x] (#66)
2 parents ee66eca + 7e4bc3a commit 9e63a88

34 files changed

Lines changed: 2682 additions & 3 deletions

‎.github/workflows/test-publish.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Manual rehearsal of the release pipeline against TestPyPI
2+
# (https://test.pypi.org), so a build can be exercised end-to-end — gate,
3+
# build, upload, pip install — without the release hitting the real index.
4+
# Run it from the Actions tab against any branch or tag.
5+
#
6+
# Mirrors python-publish.yml stage for stage (test gate -> build -> publish).
7+
# The deliberate differences:
8+
# - trigger: manual (workflow_dispatch) instead of a published release
9+
# - index: TestPyPI via repository-url, never PyPI
10+
# - version: the local segment (+g<sha>) is stripped at build time, because
11+
# PyPI-family indexes reject local versions; the no-local-version override
12+
# keeps rehearsal uploads unique per commit (e.g. 0.10.0.dev3).
13+
#
14+
# One-time setup before the first run:
15+
# 1. On test.pypi.org, add a trusted publisher for requirements-as-code
16+
# pointing at this repository, this workflow file (test-publish.yml),
17+
# and the `testpypi` environment.
18+
# 2. In the repository settings, create the `testpypi` environment.
19+
#
20+
# Install a rehearsal build (deps come from real PyPI via the extra index):
21+
# pip install --index-url https://test.pypi.org/simple/ \
22+
# --extra-index-url https://pypi.org/simple/ \
23+
# requirements-as-code==<rehearsal version>
24+
25+
name: Test Publish (TestPyPI)
26+
27+
on:
28+
workflow_dispatch:
29+
30+
permissions:
31+
contents: read
32+
33+
jobs:
34+
test:
35+
# Same gate as the real release: the full battery grid must pass before
36+
# anything is built or uploaded, so the rehearsal proves the gate too.
37+
uses: ./.github/workflows/tests.yml
38+
39+
rehearsal-build:
40+
needs: test
41+
runs-on: ubuntu-latest
42+
43+
steps:
44+
- uses: actions/checkout@v4
45+
with:
46+
# setuptools-scm derives the version from git tags, so we need the
47+
# full history + tags (the default shallow checkout omits them).
48+
fetch-depth: 0
49+
50+
- uses: actions/setup-python@v5
51+
with:
52+
python-version: "3.x"
53+
54+
- name: Build rehearsal distributions
55+
env:
56+
# Strip the +g<sha> local segment; TestPyPI rejects local versions.
57+
SETUPTOOLS_SCM_OVERRIDES_FOR_REQUIREMENTS_AS_CODE: '{ local_scheme = "no-local-version" }'
58+
run: |
59+
python -m pip install build
60+
python -m build
61+
62+
- name: Upload distributions
63+
uses: actions/upload-artifact@v4
64+
with:
65+
name: testpypi-dists
66+
path: dist/
67+
68+
testpypi-publish:
69+
runs-on: ubuntu-latest
70+
needs:
71+
- rehearsal-build
72+
permissions:
73+
# Mandatory for trusted publishing (same mechanism as the real publish).
74+
id-token: write
75+
76+
environment:
77+
name: testpypi
78+
url: https://test.pypi.org/p/requirements-as-code
79+
80+
steps:
81+
- name: Retrieve release distributions
82+
uses: actions/download-artifact@v4
83+
with:
84+
name: testpypi-dists
85+
path: dist/
86+
87+
- name: Publish release distributions to TestPyPI
88+
uses: pypa/gh-action-pypi-publish@release/v1
89+
with:
90+
repository-url: https://test.pypi.org/legacy/
91+
packages-dir: dist/

‎.github/workflows/tests.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@ jobs:
8383
paths: "tests/test_repository.py tests/test_repository_perf.py"
8484
- name: explorer
8585
paths: "tests/test_explorer_adapter.py tests/test_explorer_app.py tests/test_explorer_cli.py tests/test_explorer_commands.py tests/test_explorer_editor.py tests/test_explorer_isolation.py tests/test_explorer_workspace.py"
86+
- name: mcp
87+
paths: "tests/test_mcp_server.py tests/test_mcp_tools.py tests/test_mcp_isolation.py"
8688
- name: relationships
8789
paths: "tests/test_relationships.py tests/test_relationships_cmd.py tests/test_relationship_validation.py"
8890
- name: resolve

‎README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Requirements as Code
22

3+
<picture>
4+
<source media="(prefers-color-scheme: dark)" srcset="rac/assets/images/lore-header-dark.png">
5+
<source media="(prefers-color-scheme: light)" srcset="rac/assets/images/lore-header-light.png">
6+
<img alt="Lore — agents that know why. Deterministic. Read-only. No RAG, no guessing." src="rac/assets/images/lore-header-light.png">
7+
</picture>
8+
39
[![CI](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml/badge.svg)](https://github.com/tcballard/requirements-as-code/actions/workflows/ci.yml)
410
[![PyPI](https://img.shields.io/pypi/v/requirements-as-code)](https://pypi.org/project/requirements-as-code/)
511

@@ -69,9 +75,81 @@ Everything stays plain Markdown — see **[docs/artifacts.md](docs/artifacts.md)
6975
- [Artifact types](docs/artifacts.md) — the five types and their sections
7076
- [Relationships](docs/relationships.md) — link artifacts and validate the links
7177
- [Repository workflow](docs/repo-workflow.md) — organize a repo with RAC
78+
- [Guide (MCP server)](docs/mcp.md) — connect coding agents to your repository
7279
- [Testing & contributing](docs/testing.md) — local setup and verification
7380
- [Examples](docs/examples.md) — small, realistic artifacts
7481

82+
## RAC Guide — MCP server for coding agents
83+
84+
RAC Guide is an MCP server that serves your repository's requirements,
85+
decisions, designs, and roadmaps to coding agents as callable tools, so
86+
recorded decisions are respected instead of rediscovered. A single
87+
`pip install` is all that is needed — no separate package, no extra flag.
88+
89+
```bash
90+
rac mcp # serve the current directory
91+
rac mcp --root path/to/repo
92+
```
93+
94+
### Configure your client
95+
96+
**Claude Code**
97+
98+
```bash
99+
claude mcp add rac-guide -- rac mcp --root /path/to/your/repo
100+
```
101+
102+
Or add to `.mcp.json` in your project root:
103+
104+
```json
105+
{
106+
"mcpServers": {
107+
"rac-guide": {
108+
"command": "rac",
109+
"args": ["mcp", "--root", "/path/to/your/repo"]
110+
}
111+
}
112+
}
113+
```
114+
115+
<!-- TODO: verify against Claude Code <version> before release -->
116+
117+
**Claude Desktop** — add to `claude_desktop_config.json`:
118+
119+
```json
120+
{
121+
"mcpServers": {
122+
"rac-guide": {
123+
"command": "rac",
124+
"args": ["mcp", "--root", "/path/to/your/repo"]
125+
}
126+
}
127+
}
128+
```
129+
130+
<!-- TODO: verify against Claude Desktop <version> before release -->
131+
132+
**Cursor** — add to `.cursor/mcp.json` in your project:
133+
134+
```json
135+
{
136+
"mcpServers": {
137+
"rac-guide": {
138+
"command": "rac",
139+
"args": ["mcp", "--root", "/path/to/your/repo"]
140+
}
141+
}
142+
}
143+
```
144+
145+
<!-- TODO: verify against Cursor <version> before release -->
146+
147+
Want to try Guide against a ready-made corpus before pointing it at your own
148+
repository? See **[examples/guide/](examples/guide/)**.
149+
150+
Full onboarding path, troubleshooting, and first-question walkthrough:
151+
**[docs/mcp.md](docs/mcp.md)**.
152+
75153
## How RAC earns trust
76154

77155
RAC asks you to trust it with your product knowledge, so it holds itself to the

0 commit comments

Comments
 (0)