Plan-driven orchestration, atomic skills, review + grounding axes, diagrams

.github/agents/pharaoh.activity-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+handoffs: []
+---
+
+# @pharaoh.activity-diagram-draft
+
+Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+
+See [`skills/pharaoh-activity-diagram-draft/SKILL.md`](../../skills/pharaoh-activity-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.api-coverage-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in needs.json. Reverse direction of pharaoh-req-from-code — language-parametric via the shared regex table; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold.
+handoffs: []
+---
+
+# @pharaoh.api-coverage-check
+
+Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in `needs.json`. Reverse direction of `pharaoh-req-from-code` — language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md`; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold.
+
+See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, failure modes, and composition patterns.

.github/agents/pharaoh.block-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections.
+handoffs: []
+---
+
+# @pharaoh.block-diagram-draft
+
+Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections.
+
+See [`skills/pharaoh-block-diagram-draft/SKILL.md`](../../skills/pharaoh-block-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.bootstrap.agent.md

@@ -0,0 +1,13 @@
+---
+description: Inject minimum sphinx-needs configuration into an existing Sphinx project so sphinx-build produces a valid needs.json.
+handoffs:
+  - label: Detect and scaffold Pharaoh
+    agent: pharaoh.setup
+    prompt: Detect the freshly configured sphinx-needs project and scaffold pharaoh.toml
+---
+
+# @pharaoh.bootstrap
+
+Inject the minimum sphinx-needs configuration — extension entry, need types, optional extra links — into an existing Sphinx project that does not yet have sphinx-needs configured. Does not seed RST content, does not build, does not write `pharaoh.toml`.
+
+See [`skills/pharaoh-bootstrap/SKILL.md`](../../skills/pharaoh-bootstrap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.class-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association).
+handoffs: []
+---
+
+# @pharaoh.class-diagram-draft
+
+Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association).
+
+See [`skills/pharaoh-class-diagram-draft/SKILL.md`](../../skills/pharaoh-class-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.component-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view.
+handoffs: []
+---
+
+# @pharaoh.component-diagram-draft
+
+Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view.
+
+See [`skills/pharaoh-component-diagram-draft/SKILL.md`](../../skills/pharaoh-component-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.decision-review.agent.md

@@ -0,0 +1,10 @@
+---
+description: Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+handoffs: []
+---
+
+# @pharaoh.decision-review
+
+Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+
+See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification.

.github/agents/pharaoh.deployment-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks).
+handoffs: []
+---
+
+# @pharaoh.deployment-diagram-draft
+
+Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks).
+
+See [`skills/pharaoh-deployment-diagram-draft/SKILL.md`](../../skills/pharaoh-deployment-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.diagram-lint.agent.md

@@ -0,0 +1,13 @@
+---
+description: Walk a directory of RST files and check every `.. mermaid::` / `.. uml::` block against the real renderer parser (mmdc, plantuml). Catches silent parse failures that sphinx-build misses.
+handoffs:
+  - label: Aggregate into quality gate
+    agent: pharaoh.quality-gate
+    prompt: Consume the diagram-lint findings alongside review/mece/coverage reports for the terminal pass/fail decision
+---
+
+# @pharaoh.diagram-lint
+
+Walk a directory of RST files, extract every Mermaid / PlantUML block, and parse each block with the real renderer CLI (`mmdc -i tmp.mmd -o /dev/null`, `plantuml -checkonly`). Emits structured findings. Read-only — does not modify RST. When a renderer CLI is unavailable, degrades gracefully with a warning and install command.
+
+See [`skills/pharaoh-diagram-lint/SKILL.md`](../../skills/pharaoh-diagram-lint/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.diagram-review.agent.md

@@ -0,0 +1,10 @@
+---
+description: Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes.
+handoffs: []
+---
+
+# @pharaoh.diagram-review
+
+Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes.
+
+See [`skills/pharaoh-diagram-review/SKILL.md`](../../skills/pharaoh-diagram-review/SKILL.md) for the full atomic specification.

.github/agents/pharaoh.dispatch-signal-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify declared execution_mode in plan.yaml matches observed artefacts in runs/.
+handoffs: []
+---
+
+# @pharaoh.dispatch-signal-check
+
+Verify declared execution_mode in plan.yaml matches observed artefacts in runs/.
+
+See [`skills/pharaoh-dispatch-signal-check/SKILL.md`](../../skills/pharaoh-dispatch-signal-check/SKILL.md) for the full atomic specification.

.github/agents/pharaoh.execute-plan.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when executing a plan.
+handoffs: []
+---
+
+# @pharaoh.execute-plan
+
+Use when executing a plan.
+
+See [`skills/pharaoh-execute-plan/SKILL.md`](../../skills/pharaoh-execute-plan/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.fault-tree-diagram-draft.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors).
+handoffs: []
+---
+
+# @pharaoh.fault-tree-diagram-draft
+
+Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors).
+
+See [`skills/pharaoh-fault-tree-diagram-draft/SKILL.md`](../../skills/pharaoh-fault-tree-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-balance.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs).
+handoffs: []
+---
+
+# @pharaoh.feat-balance
+
+Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs).
+
+See [`skills/pharaoh-feat-balance/SKILL.md`](../../skills/pharaoh-feat-balance/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-component-extract.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files.
+handoffs: []
+---
+
+# @pharaoh.feat-component-extract
+
+Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files.
+
+See [`skills/pharaoh-feat-component-extract/SKILL.md`](../../skills/pharaoh-feat-component-extract/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-draft-from-docs.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files.
+handoffs: []
+---
+
+# @pharaoh.feat-draft-from-docs
+
+Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files.
+
+See [`skills/pharaoh-feat-draft-from-docs/SKILL.md`](../../skills/pharaoh-feat-draft-from-docs/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-file-map.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when mapping one feature (already emitted as an RST directive) to the source files that implement it.
+handoffs: []
+---
+
+# @pharaoh.feat-file-map
+
+Use when mapping one feature (already emitted as an RST directive) to the source files that implement it.
+
+See [`skills/pharaoh-feat-file-map/SKILL.md`](../../skills/pharaoh-feat-file-map/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-flow-extract.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files.
+handoffs: []
+---
+
+# @pharaoh.feat-flow-extract
+
+Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files.
+
+See [`skills/pharaoh-feat-flow-extract/SKILL.md`](../../skills/pharaoh-feat-flow-extract/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.feat-review.agent.md

@@ -0,0 +1,10 @@
+---
+description: Audit a single feature-level need against the generic feat review axes plus any project-specific addenda.
+handoffs: []
+---
+
+# @pharaoh.feat-review
+
+Audit a single feature-level need against the generic feat review axes plus any project-specific addenda.
+
+See [`skills/pharaoh-feat-review/SKILL.md`](../../skills/pharaoh-feat-review/SKILL.md) for the full atomic specification.

.github/agents/pharaoh.fmea-review.agent.md

@@ -0,0 +1,10 @@
+---
+description: Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness.
+handoffs: []
+---
+
+# @pharaoh.fmea-review
+
+Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness.
+
+See [`skills/pharaoh-fmea-review/SKILL.md`](../../skills/pharaoh-fmea-review/SKILL.md) for the full atomic specification.

.github/agents/pharaoh.gate-advisor.agent.md

@@ -0,0 +1,10 @@
+---
+description: Read a project's `pharaoh.toml` and report which phased-enablement ladder step is the recommended next gate to switch on. Advisory, read-only — walks the fixed 5-step ladder in order (`require_verification` → `require_change_analysis` → `require_mece_on_release` → `codelinks.enabled` → `strictness = "enforcing"`) and names the first unmet step plus its blocker.
+handoffs: []
+---
+
+# @pharaoh.gate-advisor
+
+Read the project's `pharaoh.toml`, parse the five ladder flags, and emit a findings JSON naming the next recommended gate to enable, the blocker that must be cleared first, and the full fixed ladder. Read-only; never edits `pharaoh.toml`. The ladder rationale lives in [`skills/shared/gate-enablement.md`](../../skills/shared/gate-enablement.md) — this atom is the tool that walks it, not the authority that defines it.
+
+See [`skills/pharaoh-gate-advisor/SKILL.md`](../../skills/pharaoh-gate-advisor/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, ladder table, rationale map, tailoring extension point, and composition patterns.

.github/agents/pharaoh.id-allocate.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs.
+handoffs: []
+---
+
+# @pharaoh.id-allocate
+
+Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs.
+
+See [`skills/pharaoh-id-allocate/SKILL.md`](../../skills/pharaoh-id-allocate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.id-convention-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify that every need id in a sphinx-needs corpus matches the regex declared for its type in .pharaoh/project/id-conventions.yaml. Emits a list of violations.
+handoffs: []
+---
+
+# @pharaoh.id-convention-check
+
+Verify that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Emits a list of violations.
+
+See [`skills/pharaoh-id-convention-check/SKILL.md`](../../skills/pharaoh-id-convention-check/SKILL.md) for the full atomic specification — inputs, outputs, detection rule, and composition patterns.

.github/agents/pharaoh.link-completeness-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify outgoing-link coverage across a full needs.json graph against required/optional link types declared per artefact type in artefact-catalog.yaml — missing required links, unresolved target ids, per-type policy enforcement.
+handoffs: []
+---
+
+# @pharaoh.link-completeness-check
+
+Verify outgoing-link coverage across a full needs.json graph against required/optional link types declared per artefact type in `artefact-catalog.yaml` — missing required links, unresolved target ids, per-type policy enforcement.
+
+See [`skills/pharaoh-link-completeness-check/SKILL.md`](../../skills/pharaoh-link-completeness-check/SKILL.md) for the full atomic specification — inputs, outputs, per-pass detection rules, and composition patterns.

.github/agents/pharaoh.output-validate.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object).
+handoffs: []
+---
+
+# @pharaoh.output-validate
+
+Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object).
+
+See [`skills/pharaoh-output-validate/SKILL.md`](../../skills/pharaoh-output-validate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.papyrus-non-empty-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify that a Papyrus workspace received at least N writes during a plan run.
+handoffs: []
+---
+
+# @pharaoh.papyrus-non-empty-check
+
+Verify that a Papyrus workspace received at least N writes during a plan run.
+
+See [`skills/pharaoh-papyrus-non-empty-check/SKILL.md`](../../skills/pharaoh-papyrus-non-empty-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.prose-migrate.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files.
+handoffs: []
+---
+
+# @pharaoh.prose-migrate
+
+Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files.
+
+See [`skills/pharaoh-prose-migrate/SKILL.md`](../../skills/pharaoh-prose-migrate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.quality-gate.agent.md

@@ -0,0 +1,10 @@
+---
+description: Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements).
+handoffs: []
+---
+
+# @pharaoh.quality-gate
+
+Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements).
+
+See [`skills/pharaoh-quality-gate/SKILL.md`](../../skills/pharaoh-quality-gate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.reproducibility-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Diff two output directories produced by two runs of the same plan to confirm the build is reproducible. Consumes baseline dir, rerun dir, and optional mask rules for non-deterministic fields (timestamps, random ids); emits drifted-file list with per-file changed-field summaries. Does NOT run the plan — that is the caller's responsibility (`pharaoh-execute-plan`).
+handoffs: []
+---
+
+# @pharaoh.reproducibility-check
+
+Diff two output directories produced by running the same plan twice to confirm the build is reproducible. Consumes a baseline directory, a rerun directory, and an optional list of mask rules for known-non-deterministic fields (timestamps, randomly-generated ids); emits a list of drifted files with per-file changed-field summaries. Does NOT run the plan — running twice is the caller's responsibility (`pharaoh-execute-plan`).
+
+See [`skills/pharaoh-reproducibility-check/SKILL.md`](../../skills/pharaoh-reproducibility-check/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, failure modes, and composition patterns.

.github/agents/pharaoh.req-code-grounding-check.agent.md

@@ -0,0 +1,10 @@
+---
+description: Verify a drafted requirement's claims against the source file it cites via :source_doc: — exception raise sites, trigger conditions, type-framework imports, named symbols, weasel adjectives, quantifier enumeration, branch count.
+handoffs: []
+---
+
+# @pharaoh.req-code-grounding-check
+
+Verify a drafted requirement's claims against the source file it cites via `:source_doc:` — exception raise sites, trigger conditions, type-framework imports, named symbols, weasel adjectives, quantifier enumeration, branch count.
+
+See [`skills/pharaoh-req-code-grounding-check/SKILL.md`](../../skills/pharaoh-req-code-grounding-check/SKILL.md) for the full atomic specification — inputs, outputs, per-axis detection rules, and composition patterns.