Help us improve
Share bugs, ideas, or general feedback.
From pharaoh
Authors or modifies single sphinx-needs artefacts (requirements, architecture elements, test cases, decisions) by routing to type-specific drafting skills based on project artefact catalog. Returns RST directive with ID, file placement suggestion, and parent link.
npx claudepluginhub useblocks/pharaoh --plugin pharaohHow this skill is triggered — by the user, by Claude, or both
Slash command
/pharaoh:pharaoh-authorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Invoke when the user wants to create or modify one sphinx-needs artefact (one need per call)
Drafts single sphinx-needs architecture elements (e.g., arch, swarch, module) from parent requirements, emitting RST directive blocks with :satisfies: traceability links.
Creates ADRs in MADR format, arc42 documentation, and plan-context.md for architecture proposals. Handles branch verification, GitHub issue/PR creation, artifact triage, and backlog updates.
Orchestrates multi-agent generation of artifacts like SAD, test plans, deployment plans, requirements specs, and threat models via Primary Author → parallel reviewers → synthesizer → archive pattern.
Share bugs, ideas, or general feedback.
Invoke when the user wants to create or modify one sphinx-needs artefact (one need per call) and needs the right atomic drafting skill picked for them based on the artefact type.
This skill is a thin type-router. It does not author content itself — it dispatches to one of
the atomic drafting skills (pharaoh-req-draft, pharaoh-arch-draft, pharaoh-vplan-draft,
pharaoh-decide) and forwards their RST output verbatim, plus a file-placement hint and the
parent link.
Do NOT use when:
pharaoh-flow.pharaoh-req-review, pharaoh-arch-review,
or pharaoh-verify instead.This is a compositional orchestrator. The atomicity criterion (a) does not apply: by design it dispatches to one atomic skill. Scope is bounded to "one artefact → one drafted directive".
.pharaoh/project/artefact-catalog.yaml. Common values: req, gd_req, arch,
tc, decision, plus ISO 26262 safety-V types hazard, safety_goal, fsr, tsr.
Synonyms are tolerated — e.g. requirement → req/gd_req, architecture / spec →
arch, test_case / verification → tc, safety_requirement → fsr/tsr.feature_context / element_description / parent claim depending on the dispatch target.:satisfies: or :verifies:..pharaoh/project/):
artefact-catalog.yaml — used to resolve target_type to a known prefix and confirm a
drafter is availableid-conventions.yaml — read by the dispatched drafter (not by this skill directly)The drafted RST directive block exactly as produced by the dispatched skill, plus a thin authoring-summary block:
=== [ARTEFACT] <type>: <id> ===
<RST directive block from the dispatched drafter>
=== [AUTHORING SUMMARY] ===
{
"need_id": "<id>",
"type": "<resolved target_type>",
"dispatched_skill": "pharaoh-req-draft|pharaoh-arch-draft|pharaoh-vplan-draft|pharaoh-decide",
"parent_link": "<id or null>",
"file_placement": "<suggested .rst path>",
"stop_reason": null
}
If the dispatched drafter returns a hard FAIL or [DIAGNOSTIC], forward it verbatim and set
stop_reason in the summary.
Normalise the user-supplied type to a catalog key:
| User input (any case) | Resolves to |
|---|---|
req, requirement, gd_req, comp_req, sysreq, swreq, feat | the catalog key matching the user's target_type exactly when present; otherwise the catalog key whose suffix matches the request and which appears first in artefact-catalog.yaml's declaration order. If two or more catalog keys match equally, FAIL with a clear ambiguous target_type error and list the candidates so the caller can resolve |
hazard | hazard (catalog key) |
safety_goal, sg | safety_goal (catalog key) |
fsr, safety_requirement_functional, functional_safety_requirement | fsr (catalog key) |
tsr, safety_requirement_technical, technical_safety_requirement | tsr (catalog key) |
arch, architecture, spec, specification, module, component, interface | arch |
tc, test_case, test, verification_plan, vplan | tc |
decision, dec, adr | decision |
If the user's input does not map to a key present in .pharaoh/project/artefact-catalog.yaml,
emit:
FAIL: target_type "<value>" is not in the project's artefact catalog.
Catalog keys available: <list>.
Read .pharaoh/project/artefact-catalog.yaml to confirm the resolved key exists. If the
catalog file is missing, fall back to the bundled defaults — gd_req, arch, tc — and note
the fallback in the authoring summary.
Apply the routing table:
| Resolved key | Dispatched skill | Notes |
|---|---|---|
req, gd_req, comp_req, sysreq, swreq, feat, or any key whose suffix matches req; ISO 26262 safety-V types (hazard, safety_goal, fsr, tsr) | pharaoh-req-draft | type-agnostic; target_level forwarded verbatim. Safety-V types route here because pharaoh-req-draft is the canonical drafter for any requirement-shaped artefact and reads required fields / links / metadata fields from the catalog. |
any catalog key whose suffix matches arch (e.g. arch, swarch, sys-arch) or whose synonym in the Step 0 table resolves to architecture (module, component, interface) | pharaoh-arch-draft | type-agnostic; target_level forwarded verbatim |
any catalog key whose suffix matches tc, test, vplan, or safety_v | pharaoh-vplan-draft | type-agnostic; target_level forwarded verbatim |
decision | pharaoh-decide |
Routing is driven solely by the synonym table in Step 0 plus the suffix-matching rules
above. The artefact-catalog schema does not carry a category field on per-type entries
(additionalProperties: false), so the router does not read one. Any catalog-declared
type whose key matches one of the suffix patterns above routes correctly without
modification to this skill; types whose keys do not match are caught by Guardrail G2.
These routing entries were thin passthroughs in the initial pharaoh-author commit. This
update reflects the parameterised interfaces of the three drafting skills —
pharaoh-req-draft, pharaoh-arch-draft, and pharaoh-vplan-draft all now accept any
catalog-declared type via target_level (no more hardcoded arch_type ∈ {module, component, interface} allow-list, no more hardcoded tc__ prefix, no more "no drafter for
type X yet" FAIL on safety-V types). The router forwards target_level verbatim and lets
the drafter resolve prefix, required fields, required links, and required metadata fields
from artefact-catalog.yaml / id-conventions.yaml.
Pack a minimal input set per skill and invoke it. Pass through any field the user supplied; let the dispatched skill apply its own defaults and FAIL when its inputs are insufficient.
pharaoh-req-draft
target_level ← the resolved catalog key from Step 0 (e.g. gd_req, comp_req, sysreq,
swreq, hazard, safety_goal, fsr, tsr). The drafter looks up the entry in
artefact-catalog.yaml and reads required_fields, required_metadata_fields, and
required_links; if the type is missing from the catalog it FAILs with a clear
"type X not declared" messagefeature_context ← draft_seedparent_link ← parent_link (may be a workflow-id when drafting a top-level requirement)pharaoh-arch-draft
parent_req_id ← parent_linktarget_level ← the resolved catalog key from Step 0 (e.g. arch, swarch, sys-arch,
module, component, interface). The drafter looks up the entry in
artefact-catalog.yaml and the prefix in id-conventions.yaml; if either is missing it
FAILs with a clear "type X not declared" messageelement_description ← draft_seedpharaoh-vplan-draft
parent_id ← parent_linktarget_level ← the resolved catalog key from Step 0 (e.g. tc, test, vplan). The
drafter derives the directive name from target_level and the ID prefix from
id-conventions.yaml's prefixes map — a project whose test type uses prefix T_
emits compliant T_… IDs without modifying the skillverification_level ← user-supplied if present (unit / integration / system); the
drafter will FAIL on a missing or unrecognised valuepharaoh-decide
draft_seed, the :decides: link list (parsed from parent_link — comma-separated
is supported), and any decided_by / alternatives / rationale provided by the callerIf the caller provides additional fields (e.g. safety_context, tags, level), forward
them as-is. The dispatched skill ignores keys it does not recognise.
Capture the full output of the dispatched skill — the RST directive block plus any
[NOTE] / [DIAGNOSTIC] annotations.
If the dispatched skill returned a hard FAIL, propagate it verbatim and set
stop_reason = "<dispatched-skill> FAIL" in the authoring summary. Do not attempt to fix
the inputs and retry — the caller decides.
Suggest where to write the new RST directive. The author router does not write files — it only suggests a path that the caller can use.
Default placement rules:
| Dispatched skill | Suggested file |
|---|---|
pharaoh-req-draft | same directory as parent_link's source file; filename matching the project's existing convention (e.g. requirements.rst) |
pharaoh-arch-draft | sibling architecture.rst in the same directory as parent_link's source |
pharaoh-vplan-draft | tests/ subdirectory if one exists, else sibling tests.rst |
pharaoh-decide | decisions.rst next to the first :decides: target |
If parent_link is empty or its source location cannot be resolved from needs.json, emit
file_placement: null and let the caller decide.
Emit the === [ARTEFACT] === block followed by the === [AUTHORING SUMMARY] === JSON. No
prose wrapper.
If the dispatched drafter advised a follow-up (e.g. pharaoh-arch-review), preserve that
line below the summary so callers can chain.
G1 — Unknown target_type
If the resolved key is not in the artefact catalog, FAIL (Step 0). Do not invent a new artefact type at runtime.
G2 — No drafter for known type
If the resolved key is in the catalog but does not match any of the four router categories (requirement-shaped, architecture, verification-plan, decision), FAIL with the catalog key and the four supported categories listed. Do not silently fall back to a drafter. This guardrail is rarely hit in practice — the four categories cover every artefact type declared in the bundled catalogs and every safety-V type — but stays in place to make "my catalog declared a type the router does not classify" a loud error rather than a silent miscategorisation.
G3 — Dispatched drafter failed
Forward FAIL / [DIAGNOSTIC] verbatim. Record stop_reason in the summary. Do not retry.
G4 — Tailoring missing
If .pharaoh/project/artefact-catalog.yaml is absent, the dispatched drafter will operate on
its built-in defaults. Note the fallback in the authoring summary so the caller knows the
output is not catalog-validated.
After a successful authoring summary, advise the caller:
Consider running `pharaoh-verify <need_id>` to confirm the drafted artefact
addresses the substance of its parent. For a per-axis review of the prose itself,
use `pharaoh-req-review` / `pharaoh-arch-review` / `pharaoh-vplan-review`.
User input:
target_type:
archdraft_seed: "Manages the ABS pump drive circuit, including PWM duty-cycle control and over-current protection." parent_link:gd_req__abs_pump_activation
Step 0: arch resolves directly to catalog key arch.
Step 1: routing table → pharaoh-arch-draft (architecture category).
Step 2: forward parent_req_id, target_level=arch, element_description.
Step 3: pharaoh-arch-draft returns its RST block for arch__abs_pump_driver.
Step 4: gd_req__abs_pump_activation lives in docs/requirements/braking.rst.
Suggested placement: docs/requirements/architecture.rst.
Step 5 output (condensed):
=== [ARTEFACT] arch: arch__abs_pump_driver ===
.. arch:: ABS pump driver component
:id: arch__abs_pump_driver
:status: draft
:satisfies: gd_req__abs_pump_activation
The ABS pump driver component manages the pump drive circuit, controlling
output PWM duty cycle and providing over-current protection for the pump motor.
=== [AUTHORING SUMMARY] ===
{
"need_id": "arch__abs_pump_driver",
"type": "arch",
"dispatched_skill": "pharaoh-arch-draft",
"parent_link": "gd_req__abs_pump_activation",
"file_placement": "docs/requirements/architecture.rst",
"stop_reason": null
}
Consider running `pharaoh-verify arch__abs_pump_driver` to confirm the drafted
artefact addresses the substance of its parent.