Skip to content

Commit 7889ccd

Browse files
RQM-Technologies-devRQM-Technologies-dev
authored
Merge pull request #25 from RQM-Technologies-dev/codex/add-agent-recipes-section-to-docs
Add Agent Recipes, machine task manifest, and placeholder fixtures for agent integrations
2 parents 74c877d + a213751 commit 7889ccd

13 files changed

Lines changed: 560 additions & 0 deletions

‎docs/agent-tasks.json‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
{
2+
"version": "1.0",
3+
"updated_utc": "2026-04-30T00:00:00Z",
4+
"tasks": {
5+
"validate_circuit_payload": {
6+
"title": "Validate circuit payload",
7+
"status": "production",
8+
"docs": [
9+
"/api/circuits/",
10+
"/platform/canonical-circuit-boundary/",
11+
"/api/overview/"
12+
],
13+
"required_first_steps": [
14+
"Read /llms.txt",
15+
"Confirm schema target and route in Swagger UI",
16+
"Prepare payload against public rqm-circuits boundary"
17+
],
18+
"allowed_surfaces": [
19+
"rqm-api",
20+
"rqm-circuits"
21+
],
22+
"forbidden_assumptions": [
23+
"Assuming internal rqm-compiler IR is a public payload contract",
24+
"Inventing undocumented request fields"
25+
],
26+
"expected_artifacts": [
27+
"validation_request.json",
28+
"validation_response.json",
29+
"validation_error_report.md"
30+
]
31+
},
32+
"analyze_circuit": {
33+
"title": "Analyze a validated circuit",
34+
"status": "production",
35+
"docs": [
36+
"/api/circuits/",
37+
"/api/overview/"
38+
],
39+
"required_first_steps": [
40+
"Ensure payload is already validated",
41+
"Confirm analyze route in Swagger UI"
42+
],
43+
"allowed_surfaces": [
44+
"rqm-api"
45+
],
46+
"forbidden_assumptions": [
47+
"Generating synthetic analysis fields not returned by API"
48+
],
49+
"expected_artifacts": [
50+
"analyze_request.json",
51+
"analyze_response.json"
52+
]
53+
},
54+
"optimize_circuit": {
55+
"title": "Optimize a validated circuit",
56+
"status": "production",
57+
"docs": [
58+
"/api/circuits/",
59+
"/platform/optimization-engine/",
60+
"/products/verification-trust/"
61+
],
62+
"required_first_steps": [
63+
"Validate payload first",
64+
"Confirm optimize route/schema in Swagger UI",
65+
"Attach request metadata"
66+
],
67+
"allowed_surfaces": [
68+
"rqm-api",
69+
"rqm-compiler (service internal)"
70+
],
71+
"forbidden_assumptions": [
72+
"Claiming guaranteed quantum advantage",
73+
"Treating optimization candidate as committed proof without artifacts"
74+
],
75+
"expected_artifacts": [
76+
"optimize_request.json",
77+
"optimize_response.json",
78+
"optimization_diff_or_metrics.json"
79+
]
80+
},
81+
"generate_verification_report": {
82+
"title": "Generate verification/trust report",
83+
"status": "production",
84+
"docs": [
85+
"/products/verification-trust/",
86+
"/api/overview/"
87+
],
88+
"required_first_steps": [
89+
"Collect request/response artifacts",
90+
"Check available verification metadata"
91+
],
92+
"allowed_surfaces": [
93+
"rqm-api",
94+
"documentation artifact pipeline"
95+
],
96+
"forbidden_assumptions": [
97+
"Treating missing proof metadata as proof"
98+
],
99+
"expected_artifacts": [
100+
"verification-report.md",
101+
"artifact-index.json"
102+
]
103+
},
104+
"route_execution": {
105+
"title": "Route execution through provider bridge",
106+
"status": "beta",
107+
"docs": [
108+
"/api/execution/",
109+
"/platform/execution-bridges/",
110+
"/api/overview/"
111+
],
112+
"required_first_steps": [
113+
"Validate/optimize flow complete",
114+
"Confirm provider route and capabilities"
115+
],
116+
"allowed_surfaces": [
117+
"rqm-api execution",
118+
"execution bridges"
119+
],
120+
"forbidden_assumptions": [
121+
"Assuming every provider supports identical options"
122+
],
123+
"expected_artifacts": [
124+
"execution_request.json",
125+
"execution_response.json",
126+
"provider_route_metadata.json"
127+
]
128+
},
129+
"build_studio_workflow": {
130+
"title": "Build an RQM Studio workflow",
131+
"status": "production",
132+
"docs": [
133+
"/agents/recipes/studio-workflow/",
134+
"/products/rqm-studio/",
135+
"/api/overview/"
136+
],
137+
"required_first_steps": [
138+
"Define workflow states",
139+
"Map each state to documented API call",
140+
"Define trust/reporting surfaces"
141+
],
142+
"allowed_surfaces": [
143+
"rqm-studio",
144+
"rqm-api",
145+
"rqm-circuits"
146+
],
147+
"forbidden_assumptions": [
148+
"Treating Studio as canonical computational contract"
149+
],
150+
"expected_artifacts": [
151+
"studio-workflow-spec.md",
152+
"ui-copy-guidelines.md"
153+
]
154+
},
155+
"generate_api_client": {
156+
"title": "Generate typed API client",
157+
"status": "production",
158+
"docs": [
159+
"/agents/recipes/client-generation/",
160+
"/api/overview/",
161+
"/api/circuits/"
162+
],
163+
"required_first_steps": [
164+
"Confirm routes in Swagger UI",
165+
"Define typed response envelope",
166+
"Plan validate-before-optimize helper"
167+
],
168+
"allowed_surfaces": [
169+
"documented rqm-api routes"
170+
],
171+
"forbidden_assumptions": [
172+
"Generating undocumented methods",
173+
"Hard-coding inferred schemas"
174+
],
175+
"expected_artifacts": [
176+
"typed-client-source/",
177+
"tests/fixtures/",
178+
"integration-notes.md"
179+
]
180+
},
181+
"debug_payload_error": {
182+
"title": "Debug failed payload",
183+
"status": "production",
184+
"docs": [
185+
"/agents/recipes/validate-optimize/",
186+
"/api/circuits/",
187+
"/platform/canonical-circuit-boundary/"
188+
],
189+
"required_first_steps": [
190+
"Capture raw request/response",
191+
"Identify failing route",
192+
"Compare against documented boundary"
193+
],
194+
"allowed_surfaces": [
195+
"request/response artifacts",
196+
"documented schema guidance"
197+
],
198+
"forbidden_assumptions": [
199+
"Silently dropping unknown fields without recording the change"
200+
],
201+
"expected_artifacts": [
202+
"payload-error-analysis.md",
203+
"corrected_payload_candidate.json"
204+
]
205+
},
206+
"explain_research_boundary": {
207+
"title": "Explain production vs research boundary",
208+
"status": "documented",
209+
"docs": [
210+
"/agents/recipes/research-boundary/",
211+
"/products/verification-trust/",
212+
"/compiler/canonical-ir/"
213+
],
214+
"required_first_steps": [
215+
"Classify source statements by status",
216+
"Separate public API claims from conceptual claims"
217+
],
218+
"allowed_surfaces": [
219+
"documentation summaries",
220+
"status-labeled implementation notes"
221+
],
222+
"forbidden_assumptions": [
223+
"Presenting conceptual or planned features as shipped behavior"
224+
],
225+
"expected_artifacts": [
226+
"boundary-classification-table.md",
227+
"safe-language-checklist.md"
228+
]
229+
}
230+
}
231+
}

‎docs/agents/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,13 @@ You are implementing against RQM.
5050
| Quantum circuit evaluator | Compare validation/optimization outputs and trust artifacts |
5151
| Research assistant | Explore concepts while clearly labeling research vs production behavior |
5252
| Partner/evaluator | Review architecture, trust posture, and integration readiness |
53+
54+
55+
## Next: use recipes
56+
57+
- [Agent Recipes](recipes/index.md)
58+
- [Validate → Optimize Workflow](recipes/validate-optimize.md)
59+
- [RQM Studio Agent Workflow](recipes/studio-workflow.md)
60+
- [Generate an RQM API Client](recipes/client-generation.md)
61+
- [Production vs Research Boundary](recipes/research-boundary.md)
62+
- Machine-readable task manifest: [`/agent-tasks.json`](../agent-tasks.json)

‎docs/agents/recipes/client-generation.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Generate an RQM API Client
2+
3+
## Prompt template for an agent
4+
5+
```text
6+
Generate a typed RQM API client using only documented routes and schemas from /api/overview/ and Swagger UI.
7+
Never generate undocumented methods.
8+
Use typed request/response models where possible and preserve response envelope metadata.
9+
Include a validate-before-optimize helper and tests that cover documented examples only.
10+
If schema detail is unclear in docs, confirm exact route/schema in Swagger UI before implementation.
11+
```
12+
13+
## Expected modules
14+
15+
- `rqm_client/config`
16+
- `rqm_client/http`
17+
- `rqm_client/circuits`
18+
- `rqm_client/optimization`
19+
- `rqm_client/execution`
20+
- `rqm_client/errors`
21+
- `tests/fixtures`
22+
23+
## Requirements
24+
25+
1. **Source routes from Swagger/API docs.**
26+
- Use `/api/overview/` and linked route docs.
27+
- Confirm route and payload shapes in Swagger UI before code generation.
28+
29+
2. **Never generate undocumented methods.**
30+
- If a desired feature is not documented, create a TODO with “confirm in Swagger UI” note.
31+
32+
3. **Use typed request/response models where possible.**
33+
- Represent success/error envelope (`status`, `data`/`error`, `meta`).
34+
- Keep optional fields explicit rather than inferred.
35+
36+
4. **Preserve request IDs / metadata.**
37+
- Bubble up `meta` in all client return types.
38+
- Keep correlation IDs in logs and test artifacts.
39+
40+
5. **Include validate-before-optimize helper.**
41+
- Helper must block optimize requests when validation fails.
42+
- Helper should return structured validation errors.
43+
44+
6. **Add tests around documented examples only.**
45+
- Use fixtures grounded in docs.
46+
- For missing schema detail, use placeholder fixtures with explicit “confirm schema in Swagger UI” warnings.
47+
48+
## Implementation caution
49+
50+
If endpoint details in repository docs and Swagger differ, treat Swagger as the current implementation source and annotate version/date in generated client notes.

‎docs/agents/recipes/index.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Agent Recipes
2+
3+
Use these copy/paste workflows to build RQM Platform and RQM Studio integrations without guessing undocumented behavior.
4+
5+
> Always read `/llms.txt`, `/api/overview/`, and Swagger UI first. Prefer documented routes and schemas over inferred behavior.
6+
7+
## Recipe cards
8+
9+
### Validate a circuit payload
10+
- **Goal:** confirm a circuit payload is acceptable at the public boundary before downstream steps.
11+
- **Inputs:** `rqm-circuits` schema-aligned payload target (`0.2`), API base URL, request metadata.
12+
- **Expected outputs:** validation status, response envelope, error details (if invalid), stored request/response artifact JSON.
13+
- **Docs to read first:** [Circuits API](../../api/circuits.md), [Canonical Circuit Boundary](../../platform/canonical-circuit-boundary.md), [API Overview](../../api/overview.md).
14+
- **Safety/caution:** do not call optimize on unvalidated payloads; confirm exact schema in Swagger UI before implementation.
15+
16+
### Analyze a circuit
17+
- **Goal:** run documented analysis on validated payloads.
18+
- **Inputs:** validated circuit payload, analysis route confirmed in docs/Swagger, request ID.
19+
- **Expected outputs:** analysis data and metadata in standard envelope, archived JSON artifacts.
20+
- **Docs to read first:** [Circuits API](../../api/circuits.md), [API Overview](../../api/overview.md).
21+
- **Safety/caution:** never invent analysis fields not present in response; preserve `meta`.
22+
23+
### Optimize a circuit safely
24+
- **Goal:** request optimization under trust-sensitive, proof-gated posture.
25+
- **Inputs:** validated payload, confirmed optimize route/schema, optional execution intent.
26+
- **Expected outputs:** optimization candidate output, before/after metrics when available, verification/trust metadata.
27+
- **Docs to read first:** [Circuits API](../../api/circuits.md), [Optimization Engine](../../platform/optimization-engine.md), [Verification / Trust](../../products/verification-trust.md).
28+
- **Safety/caution:** use conservative claims; do not claim guaranteed advantage or undocumented speedups.
29+
30+
### Generate a verification/trust report
31+
- **Goal:** expose reproducible trust artifacts for optimization outcomes.
32+
- **Inputs:** request/response JSON artifacts, reported metrics, documented trust principles.
33+
- **Expected outputs:** verification report bundle (inputs, outputs, diffs, metadata), auditable summary.
34+
- **Docs to read first:** [Verification / Trust](../../products/verification-trust.md), [API Overview](../../api/overview.md).
35+
- **Safety/caution:** treat optimization as candidate behavior unless verified by documented outputs.
36+
37+
### Route execution through a provider bridge
38+
- **Goal:** route validated/optimized payloads through documented execution workflows.
39+
- **Inputs:** execution target/provider, validated payload, documented execution API behavior.
40+
- **Expected outputs:** execution request artifact, provider route metadata, response status.
41+
- **Docs to read first:** [Execution API](../../api/execution.md), [Execution Bridges](../../platform/execution-bridges.md), [API Overview](../../api/overview.md).
42+
- **Safety/caution:** execution options are capability-gated; confirm provider-specific requirements before submission.
43+
44+
### Build an RQM Studio workflow
45+
- **Goal:** build UX flows that orchestrate API calls while preserving platform boundaries.
46+
- **Inputs:** Studio use case, API routes, boundary rules, trust requirements.
47+
- **Expected outputs:** workflow states, user-facing labels, artifacts linked to each step.
48+
- **Docs to read first:** [Agent Portal](../index.md), [RQM Studio](../../products/rqm-studio.md), [Canonical Circuit Boundary](../../platform/canonical-circuit-boundary.md).
49+
- **Safety/caution:** Studio is workflow/UI, not the canonical computation contract.
50+
51+
### Generate an API client
52+
- **Goal:** scaffold typed integration code from documented surfaces only.
53+
- **Inputs:** Swagger/API routes, response envelope contract, documented examples.
54+
- **Expected outputs:** typed modules, error handling, fixture-based tests, validate-before-optimize helper.
55+
- **Docs to read first:** [API Overview](../../api/overview.md), [Circuits API](../../api/circuits.md), [Agent recipe: API Client Generation](client-generation.md).
56+
- **Safety/caution:** never generate undocumented methods or inferred schemas.
57+
58+
### Debug a failed payload
59+
- **Goal:** isolate request construction vs schema vs route mismatch errors.
60+
- **Inputs:** failing request/response, endpoint docs, schema target, correlation/request metadata.
61+
- **Expected outputs:** root-cause note, corrected payload candidate, regression fixture.
62+
- **Docs to read first:** [Circuits API](../../api/circuits.md), [API Overview](../../api/overview.md), [Validate → Optimize](validate-optimize.md).
63+
- **Safety/caution:** keep failure artifacts; do not “fix” by silently dropping unknown fields.
64+
65+
### Separate production API behavior from research concepts
66+
- **Goal:** keep implementation claims grounded in shipped/documented surfaces.
67+
- **Inputs:** feature description, source docs, status label (production/beta/research/planned).
68+
- **Expected outputs:** boundary classification, safe implementation notes, user-facing wording.
69+
- **Docs to read first:** [Production vs Research Boundary](research-boundary.md), [Verification / Trust](../../products/verification-trust.md), [Canonical IR](../../compiler/canonical-ir.md).
70+
- **Safety/caution:** label research-only ideas explicitly and avoid production guarantees.

0 commit comments

Comments
 (0)