Sync .github/agents and .github/prompts with useblocks/pharaoh#16

Pulls the agent and prompt template state from the upstream PR that
addresses my consolidated feedback (useblocks/pharaoh#13). Adds the
two missing user-entry agents (@pharaoh.author, @pharaoh.verify) so
the matching slash commands stop dispatching to nothing, and picks up
the description and gitignore-guidance fixes from the same upstream
branch (covers useblocks/pharaoh#11 and useblocks#12 in one shot).

Replaces the local hand-edits applied earlier in this PR for the five
agent files I had patched (pharaoh.write-plan, pharaoh.toctree-emit,
pharaoh.execute-plan, pharaoh.feat-file-map, pharaoh.setup) with the
upstream versions, so the templates stay in sync with the plugin.

Author: bburda

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

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.activity-diagram-draft
 
-Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 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

@@ -1,10 +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.
+description: Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check.
 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.
+Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check.
 
-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.
+See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.arch-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Draft a single sphinx-needs architecture element from one parent requirement.
+description: Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:.
 handoffs: []
 ---
 
 # @pharaoh.arch-draft
 
-Draft a single sphinx-needs architecture element from one parent requirement.
+Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:.
 
 See [`skills/pharaoh-arch-draft/SKILL.md`](../../skills/pharaoh-arch-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

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

@@ -1,10 +1,10 @@
 ---
-description: Audit a single architecture element against ISO 26262-8 §6 axes.
+description: Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON.
 handoffs: []
 ---
 
 # @pharaoh.arch-review
 
-Audit a single architecture element against ISO 26262-8 §6 axes.
+Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON.
 
 See [`skills/pharaoh-arch-review/SKILL.md`](../../skills/pharaoh-arch-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.audit-fanout.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus.
+description: Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list.
 handoffs: []
 ---
 
 # @pharaoh.audit-fanout
 
-Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus.
+Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list.
 
 See [`skills/pharaoh-audit-fanout/SKILL.md`](../../skills/pharaoh-audit-fanout/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.author.agent.md

@@ -0,0 +1,19 @@
+---
+description: Use when authoring or modifying a single sphinx-needs artefact (requirement, architecture element, test case, decision) by routing to the matching atomic drafting skill based on the project's artefact catalog. Returns the drafted RST directive with an ID, file placement suggestion, and parent link.
+handoffs:
+  - label: Verify Authored Need
+    agent: pharaoh.verify
+    prompt: Check that the authored artefact addresses the substance of its parent
+  - label: Review Drafted Requirement
+    agent: pharaoh.req-review
+    prompt: Audit the drafted requirement against the ISO 26262 §6 axes
+  - label: Trace the Authored Need
+    agent: pharaoh.trace
+    prompt: Trace the new artefact through all link types
+---
+
+# @pharaoh.author
+
+Use when authoring or modifying a single sphinx-needs artefact (requirement, architecture element, test case, decision) by routing to the matching atomic drafting skill based on the project's artefact catalog. Returns the drafted RST directive with an ID, file placement suggestion, and parent link.
+
+See [`skills/pharaoh-author/SKILL.md`](../../skills/pharaoh-author/SKILL.md) for the full atomic specification — inputs, dispatch table, and composition patterns.

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

@@ -1,10 +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.
+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. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 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.
+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. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 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

@@ -1,5 +1,5 @@
 ---
-description: Inject minimum sphinx-needs configuration into an existing Sphinx project so sphinx-build produces a valid needs.json.
+description: Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills.
 handoffs:
   - label: Detect and scaffold Pharaoh
     agent: pharaoh.setup
@@ -8,6 +8,6 @@ handoffs:
 
 # @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`.
+Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills.
 
 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.change.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze the impact of changing a requirement, specification, or any sphinx-needs item. Traces through all link types and codelinks to produce a Change Document.
+description: Use when analyzing the impact of changing a requirement, specification, or any sphinx-needs item, including traceability to code via codelinks
 handoffs:
   - label: MECE Check
     agent: pharaoh.mece

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

@@ -1,10 +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).
+description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 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).
+Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 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.