Fix #13: tailoring, atomic-skill, and setup gaps

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharaoh",
   "description": "AI assistant framework for sphinx-needs projects: change analysis, traceability, MECE, authoring, verification, and release management",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "useblocks"
   },

.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 from one parent requirement. The artefact type is parameterised via `target_level` (any catalog-declared architecture type — e.g. `arch`, `swarch`, `sys-arch`, `module`, `component`, `interface`). 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 from one parent requirement. The artefact type is parameterised via `target_level` (any catalog-declared architecture type — e.g. `arch`, `swarch`, `sys-arch`, `module`, `component`, `interface`). 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,6 +1,12 @@
 ---
-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: Author the affected needs
+    agent: pharaoh.author
+    prompt: Author the needs flagged in this change analysis
+  - label: Verify the affected needs
+    agent: pharaoh.verify
+    prompt: Verify the authored needs against their parents and review axes
   - label: MECE Check
     agent: pharaoh.mece
     prompt: Check the affected area for gaps and redundancies

.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.

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

@@ -1,10 +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.
+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. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 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.
+Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 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.context-gather.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Retrieve rationale memories from a Papyrus workspace before authoring or review.
+description: Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts.
 handoffs: []
 ---
 
 # @pharaoh.context-gather
 
-Retrieve rationale memories from a Papyrus workspace before authoring or review.
+Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts.
 
 See [`skills/pharaoh-context-gather/SKILL.md`](../../skills/pharaoh-context-gather/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.coverage-gap.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus.
+description: Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap.
 handoffs: []
 ---
 
 # @pharaoh.coverage-gap
 
-Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus.
+Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap.
 
 See [`skills/pharaoh-coverage-gap/SKILL.md`](../../skills/pharaoh-coverage-gap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.decide.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Record a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements.
+description: Use when recording a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements
 handoffs:
   - label: Trace Decision
     agent: pharaoh.trace

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

@@ -1,10 +1,10 @@
 ---
-description: Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup.
+description: Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings.
 handoffs: []
 ---
 
 # @pharaoh.decision-record
 
-Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup.
+Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings.
 
 See [`skills/pharaoh-decision-record/SKILL.md`](../../skills/pharaoh-decision-record/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

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

@@ -1,10 +1,10 @@
 ---
-description: Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+description: Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON.
 handoffs: []
 ---
 
 # @pharaoh.decision-review
 
-Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON.
 
-See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification.
+See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.