codebase-graph-prd-rules — Turn code into traceable business rules

What it is

A skill pair that ships like software

Each skill is a complete agent capability: an activation entry, a full execution spec, machine-readable discovery metadata, a pinned regression contract, and an executable safety validator. The repo also ships them as a pip-installable asset package with a Makefile governance entrypoint.

codebase-graph-prd-rules/
├── codebase-graph-business-rules/  # whole-project skill
│   ├── SKILL.md                    # activation entry
│   ├── prompts/<name>.md           # full execution spec
│   ├── agents/openai.yaml          # discovery metadata
│   ├── references/                 # deep rules (lazy)
│   ├── evals/eval.yaml + cases/    # 3-case regression
│   ├── examples/                   # sample rule doc
│   └── scripts/verify_skill_package.py
├── codebase-graph-module-rules/    # single-module skill
│   ├── SKILL.md · prompts/ · agents/
│   ├── references/ · evals/ · examples/
│   └── scripts/verify_skill_package.py
├── Makefile                        # make check / code-clean
├── scripts/check_secrets.py        # red-line scan
├── pyproject.toml · setup.py       # uv build → sdist/wheel
└── index.html                      # this page

◆Why this exists

Traceable — every rule carries a source location and an evidence level you can re-check.
Readable — output is written for product, operations and QA, not just engineers.
Evaluable — a static pass is never falsely reported as verified model behavior.
Two scales — one skill for a whole project, one for a single bounded module.
Safe — packages never ship real secrets, personal data, or absolute local paths.

● MIT ● Python 3.9+ ● stdlib only ● v1.0.0

The two skills

Whole project, or one module

Pick a single clearly bounded module, or scan a whole project with no module boundary. Same evidence discipline, two scopes.

	codebase-graph-business-rules	codebase-graph-module-rules
Scope	Whole project	One feature / module
Input	Project root + source scope	Feature description / module name
Output	Full integration doc: module map, entity/state, flows, per-module rules, test scope, traceability index	Specialized module doc: boundary, relationships, rules/sorting/limits, test matrix
Use when	"梳理全项目 / PRD 基线"	"梳理某个模块 / 某条规则"

Installable

Validate and drive your skills from the terminal

Installable as a wheel from the release assets, or run the validators straight from the repo — offline, static, standard-library only.

❯Install the wheel

$ uv pip install codebase-graph-prd-rules

verify-skill-package              # PASS: both skills
# install straight from the release:
#   uv pip install "codebase-graph-prd-rules @ https://github.com/xsoway/codebase-graph-prd-rules/releases/latest/download/codebase_graph_prd_rules-1.0.0-py3-none-any.whl"

❯Or run from the repo

$ make check

python3 codebase-graph-business-rules/scripts/verify_skill_package.py codebase-graph-business-rules
# → skill package contract passed: 3 eval cases, prompt, metadata, references
python3 codebase-graph-module-rules/scripts/verify_skill_package.py codebase-graph-module-rules
make code-clean   # clean + verify + build dist

Workflow

Map, extract, confirm, document

The graph finds the shape; every rule is then re-checked against source and written for non-developer readers, with an evidence level on each claim.

Map

Build the project graph first (Graphify). INFERRED edges are leads, never facts.

Extract

Track entries and call chains; pull qualification, sorting and runtime-control rules.

Confirm

Grade each rule EXTRACTED / INFERRED / source-verified against real code, SQL/XML and config.

Document

Write a Markdown rule doc under docs/ with flows and test scope; add CSV/JSON ledgers on request.

Turn code into traceable
business rules

Graph guides, source confirms

Evidence-graded output

3-case regression contract

Analyze, never act