Pharaoh
AI assistant framework for sphinx-needs projects. Pharaoh combines structured development workflows with requirements engineering intelligence to help teams author, analyze, trace, and validate requirements using AI.
Pharaoh has no runtime binary or Python package. All analysis logic is encoded in skill/agent markdown instructions. The AI is the runtime.
Quick Start
Claude Code
# Install the plugin
/plugin install pharaoh
# Run setup to detect your project and generate pharaoh.toml
/pharaoh:setup
# Analyze the impact of a change
/pharaoh:change REQ_001
# Check for traceability gaps
/pharaoh:mece
GitHub Copilot
# Run setup to scaffold agents into your project
@pharaoh.setup
# Analyze the impact of a change
@pharaoh.change REQ_001
# Check for traceability gaps
@pharaoh.mece
Skills / Agents
| Skill (Claude Code) | Agent (Copilot) | Purpose |
|---|
pharaoh:setup | @pharaoh.setup | Scaffold Pharaoh into a project -- detect structure, generate pharaoh.toml, install Copilot agents |
pharaoh:change | @pharaoh.change | Analyze impact of a change -- trace through needs links and codelinks, produce a Change Document |
pharaoh:trace | @pharaoh.trace | Navigate traceability in any direction -- show everything linked to a need across all levels |
pharaoh:mece | @pharaoh.mece | Gap and redundancy analysis -- find orphans, missing links, MECE violations |
pharaoh:author | @pharaoh.author | AI-assisted requirement authoring -- create/modify needs with proper IDs, types, and links |
pharaoh:verify | @pharaoh.verify | Validate implementations against requirements -- content-level satisfaction checks |
pharaoh:release | @pharaoh.release | Release management -- changelog from requirements, traceability coverage metrics |
pharaoh:plan | @pharaoh.plan | Structured implementation planning -- break changes into tasks with workflow enforcement |
Workflow
pharaoh:change -> pharaoh:author -> pharaoh:verify -> pharaoh:release
-> pharaoh:mece (optional, for gap analysis)
-> pharaoh:trace (optional, for exploration)
Experience Tiers
Pharaoh works with just the AI reading files. Install additional tools for a better experience.
| Tier | What's installed | Experience |
|---|
| Basic | Pharaoh only | AI reads RST/MD files directly. Works everywhere, slower on large projects. |
| Good | + ubc CLI | Fast deterministic indexing, JSON output, CI/CD compatible. |
| Best | + ubc CLI + ubCode extension | Real-time indexing, MCP integration, live validation, full schema checks. |
Configuration
pharaoh.toml
Optional. Controls Pharaoh's workflow behavior. Without this file, advisory mode applies with sensible defaults.
[pharaoh]
strictness = "advisory" # "advisory" (default) | "enforcing"
[pharaoh.id_scheme]
pattern = "{TYPE}-{MODULE}-{NUMBER}"
auto_increment = true
[pharaoh.workflow]
require_change_analysis = true
require_verification = true
require_mece_on_release = false
[pharaoh.traceability]
required_links = [
"req -> spec",
"spec -> impl",
"impl -> test",
]
[pharaoh.codelinks]
enabled = true
See pharaoh.toml.example for a fully commented template.
Advisory vs Enforcing Mode
- Advisory (default): Skills suggest the recommended workflow but never block. Tips are shown for skipped steps.
- Enforcing: Skills check prerequisites and block if not met. For example,
pharaoh:author requires pharaoh:change to be run and acknowledged first.
Project Configuration
Pharaoh reads need types, link types, and ID settings from your existing sphinx-needs configuration:
ubproject.toml (preferred) -- the [needs] sectionconf.py (fallback) -- needs_types, needs_extra_links, etc.
Pharaoh never re-defines these settings. pharaoh.toml only controls Pharaoh's own behavior on top.
sphinx-codelinks Support
When a project uses sphinx-codelinks, Pharaoh follows codelink references in change analysis and traceability. A change to a requirement surfaces affected code files, not just other requirements.
Design
See the design document for architecture details, platform support, and the full data access model.
License
MIT
useblocks