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

* fix(pharaoh-setup): infer required_links direction from edges, not link names

The previous Step 2b inferred chain direction from a heuristic table mapping
link option names to fixed chains (e.g., `implements -> "spec -> impl"`).
The table assumed a single convention (parent references child). On projects
that follow the opposite convention (child references parent via
`:implements:`), every emitted chain is the inverse of the actual edge and
`pharaoh:mece` reports 100% gaps for the source type.

Replace the heuristic table with three sources applied in priority order:

1. Built `needs.json` when available -- emit `X -> Y` only where at least
   90% of `X` instances with the link option resolve to a `Y` (and at least
   3 instances exist), so the direction matches the data the project emits.
2. Declared `outgoing`/`incoming` semantics in `[needs.links.<name>]` --
   only used when an explicit type-pair hint is supplied; the description
   alone does not identify the type pair.
3. Refuse to guess -- emit a TODO comment instead of a chain.

The type-pair declared-in-`[[needs.types]]` filter and the empty-array
fallback continue to apply to every source.

Closes #11

* fix(agents): sync agent.md descriptions with SKILL.md, fix gitignore guidance (#12)

The 71 .github/agents/pharaoh.*.agent.md files shipped with descriptions
that diverged from their source SKILL.md. Two were catastrophically
truncated at the first '.' (split caught 'e.g.' and 'index.rst'),
producing unclosed parens and backticks that broke Markdown rendering
in Copilot's review UI on downstream PRs (sphinx-needs-demo#51).

Changes:
- 61 thin-wrapper agents: regenerate description and body verbatim
  from SKILL.md frontmatter; preserve existing handoffs.
- 8 fat agents (mece, plan, change, spec, setup, decide, release,
  trace): update only the frontmatter description; leave hand-tailored
  inline content untouched.
- pharaoh.setup.agent.md Step 3: rewrite gitignore guidance to mirror
  SKILL.md Step 4b. Ignore only ephemeral subpaths
  (.pharaoh/runs/, .pharaoh/plans/, .pharaoh/session.json,
  .pharaoh/cache/); .pharaoh/project/ tailoring stays tracked.
- ci.yaml: add a guard that fails the agent-frontmatter step when the
  description has unbalanced parens, brackets, or backticks. Catches
  the truncation class that produced the original regression.

* cleanup: drop dangling pharaoh-arch-regenerate references

Removes six references in pharaoh-arch-review/SKILL.md and one in
pharaoh-arch-draft/SKILL.md to a planned-but-never-implemented
pharaoh-arch-regenerate skill: chains_from list, prose handoff hints,
and three deferred rubric axes. Re-authoring after review is a
follow-up step outside the review skill's scope.

If we later want regenerate symmetry between req and arch (i.e. ship
pharaoh-arch-regenerate as a sibling to pharaoh-req-regenerate), that
is a separate PR.

Closes part of #13 (section 6).

* arch-review: fix grammar in advisory-chain reminder

"Confirm the findings clear" parses as a sentence missing a verb;
"confirm the findings are resolved" reads cleanly. Caught in PR review.

* feat(skills): add pharaoh-author and pharaoh-verify user-entry skills

Implements the two user-entry slash commands @pharaoh.author and
@pharaoh.verify that copilot-instructions.md documents as canonical
steps in the workflow chain (@pharaoh.plan -> @pharaoh.change ->
@pharaoh.author -> @pharaoh.verify -> @pharaoh.release). Both were dead
before: prompt files only carried agent-frontmatter pointing at agent
files that did not exist, while ~26 live references in 6 sibling
agent.md files plus copilot-instructions.md called into them.

pharaoh-author is a type-routing orchestrator over the existing atomic
drafting skills (pharaoh-req-draft, pharaoh-arch-draft, pharaoh-vplan-
draft, pharaoh-decide). Dispatch entries for pharaoh-arch-draft and
pharaoh-vplan-draft are deliberately thin passthroughs -- a follow-up
in this PR will update them once those skills' interfaces are
parameterized.

pharaoh-verify is a content-level satisfaction checker -- given a
need-id, walks the :satisfies: chain and evaluates whether the child
addresses the parent's substance. Distinct from pharaoh-mece
(structural), pharaoh-req-review (per-axis rubric), and
pharaoh-tailor-review (schema-level).

Closes part of #13 (section 5).

* schemas: promote tailoring schemas to canonical install path

Moves the four JSON Schemas from examples/score/.pharaoh/project/schemas/
to schemas/ at the package root so every Pharaoh-tailored project shares
the same authoritative validation rules. Adds schemas/README.md
documenting the resolution order and per-file responsibilities.

Updates pharaoh-tailor-review to resolve schemas in priority order:
(1) explicit schemas_dir argument, (2) per-project
<tailoring_dir>/schemas/, (3) the shipped schemas/ folder, (4) fallback
to built-in structural rules with degraded_mode flag.

Fixes pharaoh-tailor-bootstrap output to validate against the canonical
artefact-catalog schema by dropping the unused child_of and lifecycle_ref
keys (both rejected by additionalProperties: false). The information
child_of carried is recoverable from artefact-type link declarations;
lifecycle_ref was decorative.

Updates skills/shared/tailoring-access.md to document only the
schema-allowed fields (required_fields, optional_fields, lifecycle,
required_body_sections) — the prior child_of and lifecycle_ref entries
were inconsistent with the canonical schema.

Closes part of #13: section 1 sub-bullets (a) artefact-catalog
additionalProperties violations and (d) schemas at canonical install
path. Sub-bullets (b) and (c) are addressed by the next commit on this
branch.

* tailor: reconcile bootstrap/fill output shapes against canonical schemas

Aligns pharaoh-tailor-bootstrap and pharaoh-tailor-fill so the same
tailoring file gets the same shape regardless of which authoring path
ran. Resolves divergences caught when validating real-world projects:

workflows.yaml: bootstrap rewrites its per-type {from, to, gate} map
output to the schema-shaped flat lifecycle_states + transitions[*]
{from, to, requires}. fill already emits this shape on the transitions
side but printed lifecycle_states as a description map; corrected to a
flat list per the schema. bootstrap was the outlier on transitions.

id-conventions.yaml id_regex_*: pharaoh-id-convention-check now reads
id_regex_exceptions (the schema key) instead of id_regex_by_type. The
three fixture files in skills/pharaoh-id-convention-check/fixtures/
move to the same key.

id-conventions.yaml prefixes: canonical value form is the identifier
prefix string (e.g. REQ_, gd_req), not a human description. Tightens
the prefixes additionalProperties regex in
schemas/id-conventions.schema.json to enforce identifier-prefix shape
and updates pharaoh-tailor-fill plus the score example tailoring to
emit prefix strings instead of prose descriptions.

pharaoh-lifecycle-check: documentation note tying the workflows.yaml
shape it consumes to schemas/workflows.schema.json; no behavioural
change.

Closes #13 sections 2 (bootstrap/fill incompatibility) and 1 sub-bullets
(b) workflows shape mismatch and (c) id-conventions value-form ambiguity.

* release-gate: emit and validate required_links/metadata_fields/roles

Closes the silent no-op where four release-gate fields were consumed
but never emitted by any tailoring author:

  required_links / optional_links     read by pharaoh-link-completeness-check
  required_metadata_fields            read by pharaoh-output-validate
  required_roles                      read by pharaoh-review-completeness

Adds all four as optional per-type properties to
schemas/artefact-catalog.schema.json. Documents inference rules in
pharaoh-tailor-bootstrap and emission defaults in pharaoh-tailor-fill.
Adds cross-file rule C6 in pharaoh-tailor-review that surfaces a
finding when any of the three required-* fields is absent (empty arrays
are valid -- they declare an explicit choice; missing keys are not).

Closes #13 (section 3).

* toml-example: document all consumed pharaoh.toml sections, single defaults source

Adds the three sections that were consumed but undocumented:

  [pharaoh.codelink_comments]   read by pharaoh-req-codelink-annotate
                                and pharaoh-req-from-code
  [pharaoh.diagrams]            read by 11 diagram-draft skills plus
                                pharaoh-feat-component-extract and
                                pharaoh-feat-flow-extract
  [pharaoh.quality_gate]        read by pharaoh-diagram-lint

Documents [pharaoh.codelinks].src_dir (consumed by pharaoh-write-plan
and pharaoh-feat-file-map) which the example previously left
undocumented under [pharaoh.codelinks].

Reconciles the workflow-flag defaults that previously disagreed across
three sources (shared/strictness.md, pharaoh-gate-advisor, the
example). The example is now the single source of truth; the other two
defer to it explicitly rather than redeclare.

Persists [pharaoh.workflow].mode as a real key (was a comment-only line
that no skill could parse).

Closes #13 (section 4).

* atomic: parameterize pharaoh-arch-draft and pharaoh-vplan-draft by target_level

Drops the hardcoded type vocabulary that locked these two atomic
drafting skills to a fixed set of artefact types:

pharaoh-arch-draft no longer accepts only arch_type in {module,
component, interface}. It now takes a target_level argument and reads
the type's required_fields and id_regex from artefact-catalog.yaml /
id-conventions.yaml. Drafting swarch, sys-arch, or any other
architecture-shaped need declared in the catalog now works without
modifying the skill.

pharaoh-vplan-draft no longer hardcodes the tc__ prefix or the tc
catalog key. The prefix is derived from id-conventions.yaml's prefixes
map for the target_level type; the catalog key matches the type name.
A project whose test type uses prefix T_ now generates compliant IDs.

pharaoh-author routing entries for both skills now pass the
parameterized target_level instead of the previous thin passthrough.
The router dispatches by artefact-catalog category, so any
catalog-declared architecture type routes to pharaoh-arch-draft and
any verification-plan-shaped type routes to pharaoh-vplan-draft.

Closes #13 section 9 sub-bullets (a) and (b).

* atomic: extend pharaoh-req-draft to cover ISO 26262 safety-V types

Reframes pharaoh-req-draft as the canonical drafter for any
requirement-shaped artefact, not just classical req / comp_req. Any
target_level declared in artefact-catalog.yaml routes here, including
ISO 26262 safety-V types: hazard (HARA outputs), safety_goal (Part 3),
and fsr / functional safety requirement (Part 4).

The skill drives every type from artefact-catalog.yaml's required_fields
and required_metadata_fields, so safety-V-specific fields like asil,
severity, exposure, controllability, and safe_state are surfaced as
placeholders without hardcoding ISO-26262 logic into the skill itself.
A project that doesn't declare these fields in its catalog gets a
plain requirement; a project that does (e.g. useblocks/sphinx-needs-demo)
gets the safety-V shape.

pharaoh-author routing for safety-V target_levels no longer FAILs with
"no drafter for type X yet" -- they dispatch to the reframed
pharaoh-req-draft like any other requirement-shaped type.

Closes #13 section 9 sub-bullet (c).

* flow: extend pharaoh-flow to SYS/SWE split and safety V

Today the orchestrator's description claims V-model end-to-end but
the body only walks the classical req -> arch -> vplan -> fmea chain.
swreq / sysreq / sys-arch / swarch never appear; hazard / safety_goal
/ fsr never appear.

Extends the chain to three optional layers:

  Safety V:   hazard -> safety_goal -> fsr   (ISO 26262 Part 3 + 4)
  SYS/SWE:    sysreq -> sys-arch
              swreq  -> swarch
  Classical:  req / comp_req -> arch -> vplan -> fmea

Each layer auto-detects from artefact-catalog.yaml: a layer runs only
if the catalog declares its types. Caller can also pass an explicit
stages argument to skip layers (e.g. run only safety_v while the rest
of the V is still being bootstrapped).

Safety-V dispatch goes to pharaoh-req-draft with the appropriate
target_level (hazard / safety_goal / fsr), not new safety-V skills —
the reframe in the prior commit makes pharaoh-req-draft the canonical
drafter for any requirement-shaped artefact.

Closes #13 section 10.

* setup: read project state before imposing defaults

pharaoh-setup now consults the project's declared conventions and
existing artefacts before generating tailoring. Six setup defects
on real-world projects (useblocks/sphinx-needs-demo) drove this:

- artefact-catalog optional_fields seeded from ubproject.toml
  [needs.fields.X], not from a Pharaoh-internal placeholder set
- workflows.yaml lifecycle_states derived from a status histogram of
  existing RST files; falls back to draft -> reviewed -> approved
  only when no project history exists
- id-conventions prefixes detect collisions in [[needs.types]] and
  warn or FAIL with a remediation hint
- id_regex shape detected from existing IDs (e.g. {DOMAIN}_{NUMBER}),
  not the prescriptive {TYPE}_{NUMBER} default
- mode classifier uses [[needs.types]] declarations and RST content,
  not the gitignored needs.json build artefact
- release-gate fields from the canonical schema (required_links,
  optional_links, required_metadata_fields, required_roles) are
  populated per type from observed link/field declarations

required_links direction inference, partially shipped in PR #14,
extended to cover the full set of relations declared in
[needs.links.X].

Closes #13 section 8.

* fix: pass target_level to pharaoh-req-draft and populate score example release-gate fields

pharaoh-author Step 2 dispatched to pharaoh-req-draft without
target_level, so a call like pharaoh-author(target_type=hazard) would
fall through pharaoh-req-draft's "default to first req-shaped catalog
key" path and emit a gd_req instead of a hazard. Same problem for
safety_goal, fsr, tsr, sysreq, swreq, and any non-default req variant.
The Step 1 routing table already advertised "target_level forwarded
verbatim" — this commit makes the dispatch block honour that.

Also populates the four release-gate fields (required_links,
optional_links, required_metadata_fields, required_roles) for every
type entry in the score example artefact-catalog. The schema added
the fields as optional, the bootstrap and setup skills emit them, but
the canonical example file was silent — leaving a copy-paste source
that disagrees with what fresh tailoring runs would produce.

* fix(review): address 11 cross-phase review findings

Critical:
- CHANGELOG.md drops local pharaoh-validation harness citations
- pharaoh-tailor-review SKILL.md drops harness-cite at line 304
- pharaoh-author drops category-field routing (schema additionalProperties:
  false rejects it); relies on synonym table only
- pharaoh-vplan-draft now defaults verification_level=system on absent input
  so pharaoh-author dispatch chain doesn't hard-FAIL
- pharaoh.setup.agent.md replaces hardcoded 8-agent list with dynamic
  enumeration from .github/agents/
- pharaoh-tailor-review prefixes-value rule no longer calls it a
  "description"; matches schema pattern

Important:
- pharaoh-author resolution rule made deterministic for ambiguous *_req
- plugin.json bumped 0.1.0 -> 0.2.0
- CHANGELOG migration section: id_regex_by_type rename, prefixes value form,
  child_of/lifecycle_ref drops, C6 behaviour
- pharaoh.author / pharaoh.verify added to handoffs of pharaoh.change and
  pharaoh.plan agents

Author: bburda

.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