Skip to content

Commit edc310d

Browse files
vparlavparla
committed
docs: add agent workflow enforcement
1 parent bf2b405 commit edc310d

9 files changed

Lines changed: 326 additions & 0 deletions

File tree

‎.codex/workflows/agent-skill-gate.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!--
2+
==========================================================================================================
3+
SPDX-License-Identifier: MIT
4+
Copyright (c) 2025 Vinny Parla
5+
File: .codex/workflows/agent-skill-gate.md
6+
Purpose: Codex workflow bridge for enforcing mcp-cpp agent and skill guardrails
7+
==========================================================================================================
8+
-->
9+
10+
# Codex Agent And Skill Gate
11+
12+
Codex should treat `agents.md` and `SKILLS.MD` as the canonical repo contract.
13+
14+
1. Read `agents.md`.
15+
2. Read `SKILLS.MD`.
16+
3. Use `.vscode/tasks.json` for repeatable editor-run Docker flows when working in VS Code.
17+
4. Use Docker-only execution, WSL on Windows, and `bash` on Linux or macOS.
18+
5. Do not use bind mounts, named volumes, `docker cp`, `-o type=local`, or any Docker pattern that writes
19+
back to the host.
20+
6. If any failure appears, even if it looks unrelated, stop and fix it before continuing.

‎.cursor/rules/00-agent-skill-enforcement.mdc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: >-
3+
Enforce agents.md and SKILLS.MD, docker-first no-host-write execution,
4+
and fail-stop remediation for every mcp-cpp task.
5+
alwaysApply: true
6+
---
7+
8+
<!--
9+
==========================================================================================================
10+
SPDX-License-Identifier: MIT
11+
Copyright (c) 2025 Vinny Parla
12+
File: .cursor/rules/00-agent-skill-enforcement.mdc
13+
Purpose: Cursor rule that enforces mcp-cpp agent and skill guardrails
14+
==========================================================================================================
15+
-->
16+
17+
# mcp-cpp Agent And Skill Enforcement
18+
19+
- Read `agents.md` and `SKILLS.MD` at session start and before each materially new task.
20+
- Select every matching skill from `SKILLS.MD` before proposing or running commands.
21+
- Use Docker only. Windows commands go through `wsl -d Ubuntu -- bash -lc "..."`.
22+
- Do not use bind mounts, named volumes, `docker cp`, `-o type=local`, or any Docker pattern that writes back to
23+
the host.
24+
- Treat every failure as blocking, even if it looks unrelated to the active request. Fix it immediately, rerun the
25+
failed gate, and only then continue.
26+
- If a task truly requires host writes, host IPC, or host network access, stop and ask the human first.

‎.github/copilot-instructions.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!--
2+
==========================================================================================================
3+
SPDX-License-Identifier: MIT
4+
Copyright (c) 2025 Vinny Parla
5+
File: .github/copilot-instructions.md
6+
Purpose: VS Code Copilot instructions for enforcing mcp-cpp agent and skill rules
7+
==========================================================================================================
8+
-->
9+
10+
# mcp-cpp Copilot Instructions
11+
12+
Start every task by reading `agents.md` and `SKILLS.MD`.
13+
14+
- Use the matching skill sections from `SKILLS.MD` before proposing commands or edits.
15+
- Run architecture checks before broader validation.
16+
- Use `.vscode/tasks.json` for repeatable editor-run Docker workflows.
17+
- Use Docker-first execution only. Windows commands go through WSL; Linux and macOS use `bash`.
18+
- Do not use bind mounts, named volumes, `docker cp`, or any Docker export that writes back to the host.
19+
- Treat every failure as blocking, even if it is not directly tied to the active request. Fix it immediately before
20+
continuing.

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,9 @@ Thumbs.db
7979
# IDE/editor metadata
8080
# -------------------
8181
.vscode/
82+
!.vscode/
83+
.vscode/*
84+
!.vscode/tasks.json
8285
.idea/
8386
*.user
8487
*.vcxproj.user

‎.vscode/tasks.json‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
{
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"label": "docker: build test image",
6+
"type": "shell",
7+
"command": "docker",
8+
"args": [
9+
"buildx",
10+
"build",
11+
"-f",
12+
"Dockerfile.demo",
13+
"--target",
14+
"test",
15+
"--progress=plain",
16+
"--pull",
17+
"--load",
18+
"-t",
19+
"mcp-cpp-test",
20+
"."
21+
],
22+
"options": {
23+
"cwd": "${workspaceFolder}"
24+
},
25+
"windows": {
26+
"command": "wsl",
27+
"args": [
28+
"-d",
29+
"Ubuntu",
30+
"--",
31+
"bash",
32+
"-lc",
33+
"cd \"$(wslpath '${workspaceFolder}')\" && docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test ."
34+
]
35+
},
36+
"problemMatcher": []
37+
},
38+
{
39+
"label": "docker: run architecture gate",
40+
"type": "shell",
41+
"command": "docker",
42+
"args": [
43+
"run",
44+
"--rm",
45+
"--network",
46+
"none",
47+
"--read-only",
48+
"--tmpfs",
49+
"/tmp:rw,noexec,nosuid,size=1g",
50+
"--entrypoint",
51+
"bash",
52+
"mcp-cpp-test",
53+
"-lc",
54+
"cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R '^Architecture' -VV --output-on-failure"
55+
],
56+
"dependsOn": "docker: build test image",
57+
"windows": {
58+
"command": "wsl",
59+
"args": [
60+
"-d",
61+
"Ubuntu",
62+
"--",
63+
"bash",
64+
"-lc",
65+
"docker run --rm --network none --read-only --tmpfs /tmp:rw,noexec,nosuid,size=1g --entrypoint bash mcp-cpp-test -lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R \"^Architecture\" -VV --output-on-failure'"
66+
]
67+
},
68+
"problemMatcher": []
69+
},
70+
{
71+
"label": "docker: run full ctest gate",
72+
"type": "shell",
73+
"command": "docker",
74+
"args": [
75+
"run",
76+
"--rm",
77+
"--network",
78+
"none",
79+
"--read-only",
80+
"--tmpfs",
81+
"/tmp:rw,noexec,nosuid,size=1g",
82+
"--entrypoint",
83+
"bash",
84+
"mcp-cpp-test",
85+
"-lc",
86+
"cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure"
87+
],
88+
"dependsOn": "docker: build test image",
89+
"windows": {
90+
"command": "wsl",
91+
"args": [
92+
"-d",
93+
"Ubuntu",
94+
"--",
95+
"bash",
96+
"-lc",
97+
"docker run --rm --network none --read-only --tmpfs /tmp:rw,noexec,nosuid,size=1g --entrypoint bash mcp-cpp-test -lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure'"
98+
]
99+
},
100+
"problemMatcher": []
101+
}
102+
]
103+
}

‎.windsurf/skills/repo-guardrails/SKILL.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!--
2+
==========================================================================================================
3+
SPDX-License-Identifier: MIT
4+
Copyright (c) 2025 Vinny Parla
5+
File: .windsurf/skills/repo-guardrails/SKILL.md
6+
Purpose: Windsurf skill for enforcing mcp-cpp repo guardrails
7+
==========================================================================================================
8+
-->
9+
10+
---
11+
name: repo-guardrails
12+
description: >-
13+
Apply mcp-cpp agent rules and repo skills to every task. Use Docker-first
14+
execution, WSL on Windows, bash on macOS/Linux, block all host-write Docker
15+
patterns, and stop immediately on any failure.
16+
---
17+
18+
# Repo Guardrails
19+
20+
Read `agents.md` first, then `SKILLS.MD`.
21+
22+
- Use the matching skill sections in `SKILLS.MD` before running commands or proposing edits.
23+
- Keep all build, test, and debug work inside Docker images built from repo context.
24+
- Do not mount the repo into containers and do not write artifacts back to the host.
25+
- If any failure appears, fix it immediately before continuing, even when it looks tangential.
26+
- Use `bash` on Linux and macOS, and `wsl -d Ubuntu -- bash -lc "..."` on Windows.

‎.windsurf/workflows/agent-skill-gate.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
description: >-
3+
Open agents.md and SKILLS.MD first, then use the repo's docker-first
4+
fail-stop workflow before any other work.
5+
---
6+
7+
<!--
8+
==========================================================================================================
9+
SPDX-License-Identifier: MIT
10+
Copyright (c) 2025 Vinny Parla
11+
File: .windsurf/workflows/agent-skill-gate.md
12+
Purpose: Windsurf workflow for enforcing mcp-cpp agent and skill guardrails
13+
==========================================================================================================
14+
-->
15+
16+
# Agent And Skill Gate
17+
18+
1. Open `agents.md`.
19+
2. Open `SKILLS.MD`.
20+
3. Select the matching skills.
21+
4. Use only the Docker command templates from `SKILLS.MD`.
22+
5. If any failure, denial, failing test, or unrelated regression appears, stop and fix it before doing anything else.
23+
6. If the only path needs host writes, host IPC, or host network access, escalate to the human first.

‎CLAUDE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!--
2+
==========================================================================================================
3+
SPDX-License-Identifier: MIT
4+
Copyright (c) 2025 Vinny Parla
5+
File: CLAUDE.md
6+
Purpose: Claude Code entrypoint for mcp-cpp repo rules and skills
7+
==========================================================================================================
8+
-->
9+
10+
# Claude Code Instructions
11+
12+
Load `@agents.md` and `@SKILLS.MD` before planning, editing, or running commands.
13+
14+
- Treat `agents.md` as the canonical policy file and `SKILLS.MD` as the execution workflow.
15+
- Use Docker-first execution only. Windows uses `wsl -d Ubuntu -- bash -lc "..."`; Linux and macOS use `bash`.
16+
- No Docker host writes: no bind mounts, named volumes, `docker cp`, or `-o type=local`.
17+
- Any failure is blocking, even if it looks unrelated to the active task. Fix it immediately, rerun the failed gate,
18+
and only then continue.
19+
- If the only path forward needs host writes, host IPC, or host network access, stop and ask the human first.

‎SKILLS.MD‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<!--
2+
==========================================================================================================
3+
SPDX-License-Identifier: MIT
4+
Copyright (c) 2025 Vinny Parla
5+
File: SKILLS.MD
6+
Purpose: Repo-local skill map for agentic tools working in mcp-cpp
7+
==========================================================================================================
8+
-->
9+
10+
# MCP C++ SDK Skills
11+
12+
`agents.md` is the canonical policy file. This file turns those rules into repeatable execution skills for
13+
Codex, Windsurf, Cursor, VS Code, and Claude Code.
14+
15+
## Load Order
16+
17+
1. Read `agents.md`.
18+
2. Read `SKILLS.MD`.
19+
3. Select every matching skill before acting.
20+
4. If any command, test, build, access check, lint, doc check, or unrelated validation fails, stop and fix it
21+
immediately before continuing.
22+
23+
## Skill: repo-governance
24+
25+
Use for every task.
26+
27+
- Reuse `include/mcp/` interfaces and shared transport/auth abstractions before adding parallel code paths.
28+
- Run architecture checks first. If architecture enforcement fails, all other work is blocked.
29+
- Keep SPDX headers, repository-relative `File:` paths, tests, and docs aligned with the change.
30+
- Never run builds, tests, or debug commands on the host.
31+
32+
## Skill: docker-first-no-host-write
33+
34+
Use for build, test, debug, inspection, or automation work that executes code.
35+
36+
- Linux and macOS commands use `bash`.
37+
- Windows commands use `wsl -d Ubuntu -- bash -lc "..."`
38+
- Build from repo context, then run from image-embedded source. Do not mount the repo into containers.
39+
- Do not use bind mounts, named volumes, `docker cp`, `-o type=local`, or any Docker pattern that writes back to
40+
the host.
41+
- Prefer `--network none`. If network or IPC is required, stop and get explicit human approval first.
42+
43+
```bash
44+
# Linux/macOS
45+
docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test .
46+
docker run --rm --network none --read-only \
47+
--tmpfs /tmp:rw,noexec,nosuid,size=1g \
48+
--entrypoint bash mcp-cpp-test \
49+
-lc "cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R '^Architecture' -VV --output-on-failure"
50+
docker run --rm --network none --read-only \
51+
--tmpfs /tmp:rw,noexec,nosuid,size=1g \
52+
--entrypoint bash mcp-cpp-test \
53+
-lc "cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure"
54+
55+
# Windows (PowerShell via WSL)
56+
wsl -d Ubuntu -- bash -lc "cd /mnt/<drive>/<path-to-repo>/mcp-cpp && \
57+
docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test ."
58+
wsl -d Ubuntu -- bash -lc "docker run --rm --network none --read-only \
59+
--tmpfs /tmp:rw,noexec,nosuid,size=1g \
60+
--entrypoint bash mcp-cpp-test \
61+
-lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -R \"^Architecture\" -VV --output-on-failure'"
62+
wsl -d Ubuntu -- bash -lc "docker run --rm --network none --read-only \
63+
--tmpfs /tmp:rw,noexec,nosuid,size=1g \
64+
--entrypoint bash mcp-cpp-test \
65+
-lc 'cp -a /src/build /tmp/build && ctest --test-dir /tmp/build -VV --output-on-failure'"
66+
```
67+
68+
Emit results to stdout or stderr only. Do not export artifacts back to the host.
69+
70+
## Skill: failure-first-remediation
71+
72+
Use whenever anything fails, including failures that look unrelated to the active task.
73+
74+
- Treat access-denied errors, safe-directory errors, failing unrelated tests, header drift, doc drift, lint issues,
75+
and Docker misconfiguration as blocking failures.
76+
- Fix the failure immediately, rerun the failed gate, then rerun the next broader gate that depends on it.
77+
- Do not scope a failure away as "out of band" or "not part of this task."
78+
79+
## Skill: review-and-delivery
80+
81+
Use when reviewing or finalizing work.
82+
83+
- Findings come first in reviews, with file and line references.
84+
- For implementation work, verify the architecture gate before broader test suites.
85+
- If repository rules and tool rules conflict, obey the stricter rule and update the enforcement docs in the same
86+
change.

0 commit comments

Comments
 (0)