Imported from scardoso-lu/fabric-skills-settings (AGENTS.md). Install upstream with npx skills add scardoso-lu/fabric-skills-settings. Copyright stays with the author.

Fabric Agent Pack — Codex Contributor Guidance

This repository is the source package and installer for Microsoft Fabric agent profiles. It is not the day-to-day Fabric project workspace. Install the CLI with uv tool install fabric-vibecoding-settings (or pip install fabric-vibecoding-settings). Then run fabric-vibecoding-agents install --profile codex --target /path/to/repo and open Codex from that target repo root. Use fabric-vibe <group> <cmd> inside the target for daily helpers.

Architecture at a glance

The repo has three top-level packages:

• cli/ — everything installed on the user's laptop: the wheel installer, profile entrypoints + 4 subagents (Claude + Codex), setup scripts, and the target-side tools shipped to tool/ in the target repo. Tools in cli/tools/ are invoked via Bash, not MCP.
• server/ — FastMCP HTTP server (Docker). Serves graph knowledge tools plus fabric helpers that run without ms-fabric-cli. Start it with docker compose up from the repo root.

Source-package invariants (layout + profile guidance) are enforced by pytest modules tests/test_install_package.py and tests/test_agent_guidance.py, backed by importable logic in tests/_validation/.

See docs/architecture.md for diagrams.

MCP server capabilities (server/)

The fabric-server MCP container exposes:

The server has no filesystem access to the user's project. pipeline_lineage_check accepts uploaded file contents; data_mock_generate requires a target_dir mounted into the container.

CLI / Bash tool capabilities (cli/tools/ → installed as tool/)

Tools shipped to the target repo's tool/ dir and invoked via Bash. Fabric helper commands that talk to Fabric require ms-fabric-cli (uv tool install ms-fabric-cli) and SPN credentials in .env:

Source package layout

Knowledge graph

• Sources: server/content/**/*.md, server/skills/*/SKILL.md (+ sections/). Curated edges from frontmatter links:; auto edges from path mentions in prose.
• Build: server/builders/build-graph.py writes dist/.graph/{graph.json, graph-bm25.pkl, *.html, *.svg}. Run via uv run --group dev python server/builders/build-graph.py --target . --stats.
• Served live: the running Docker container loads dist/.graph/ on startup and serves all graph tools. CRUD calls (graph_create_node etc.) trigger an atomic in-memory rebuild — no restart needed.

Skills

Skill source files live only under server/skills/. They are served via the graph (graph_get_node('skills/<name>')) — not shipped to target repos.

Installed skills: rtk, fabric-ingest, fabric-transform, fabric-model, fabric-validate, fabric-notebook-loop, fabric-ops, fabric-pipeline, semantic-model, mock-data, prd, grill-me, git-commit, caveman.

Long skills (> 150 lines) are split into sections/ under the skill folder. Gated by SPLIT_SKILLS in tests/test_skill_split_coverage.py.

File scanning

Always exclude .venv/ when searching.

Development rules

• Keep vendor-specific runtime assets inside their profile folders. No root .claude/ or .codex/ directories.
• Skill source is single-source under server/skills/. Do not duplicate elsewhere.
• Build-time graph code (server/builders/) is NOT installed into target repos; only runtime code in server/graph/ and server/tools/ runs in Docker.
• cli/tools/ is the single source of truth for installable target helpers. cli/profiles/shared/scaffold/ only carries verbatim scaffold files (data/sandbox/, workspace/); .mcp.json is generated by the target bootstrap, not shipped.
• When changing installer logic, edit modules under cli/src/fabric_skills_settings/ (Typer CLI in cli.py; subcommands in commands/; shared logic in core/). Run uv build to verify wheel content.
• If installer refresh must recognize a helper, update REFRESHABLE_SCAFFOLD_MARKERS in cli/src/fabric_skills_settings/core/markers.py.
• Never commit .env, credentials, tokens, connection strings, data files, logs, generated notebook bundles, or __pycache__/.
• Use placeholders only in .env.example.
• Fabric CLI wrappers must not execute caller-controlled binaries.
• Fabric credentials pass through environment variables or approved secret stores only — never command-line arguments.
• RTK setup stays pinned to a specific release and verifies downloaded assets against the release checksum.
• Profile entrypoints (cli/profiles/claude/CLAUDE.md, cli/profiles/codex/AGENTS.md) must stay ≤ 50 lines with no operational section headings. Enforced by tests/test_agent_guidance.py (logic in tests/_validation/agent_guidance.py).

Required checks

After changing profiles, installer logic, guidance, validation, or installable tooling, run the test suite — it now includes the layout + agent-guidance validators:

uv run --group dev pytest                                  # all unit tests + validators

# Run just the source-package validators:
uv run --group dev pytest tests/test_install_package.py tests/test_agent_guidance.py

For an end-to-end install smoke test against a real target repo:

fabric-vibecoding-agents install --profile all --target <target-repo> --dry-run
fabric-vibecoding-agents check   --profile all --target <target-repo>

Commit / PR handoff

State what changed, which validations were run, whether a target-repo smoke test was performed, and any failures or limitations encountered.