✨ Pharaoh + sphinx-needs agile traceability with sphinx-codelinks

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

@@ -0,0 +1,10 @@
+---
+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
+
+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, atomicity contract, and composition patterns.

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

@@ -0,0 +1,10 @@
+---
+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
+
+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

@@ -0,0 +1,10 @@
+---
+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
+
+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

@@ -0,0 +1,10 @@
+---
+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
+
+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

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

@@ -0,0 +1,13 @@
+---
+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
+    prompt: Detect the freshly configured sphinx-needs project and scaffold pharaoh.toml
+---
+
+# @pharaoh.bootstrap
+
+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

@@ -0,0 +1,131 @@
+---
+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
+  - label: Trace Requirement
+    agent: pharaoh.trace
+    prompt: Trace the changed requirement through all levels
+---
+
+# @pharaoh.change: Change Impact Analysis
+
+Analyze the full impact of a proposed change to any sphinx-needs item. Trace through ALL link types -- standard `links`, `extra_links` (implements, tests, etc.), and sphinx-codelinks -- to produce a structured Change Document listing every affected need and code file with a recommended action.
+
+## Data Access
+
+Use the best available data source in this priority order:
+
+1. **ubc CLI**: Run `ubc --version`. If available, use `ubc build needs --format json` for the needs index. Use `ubc diff` for structural change detection.
+2. **ubCode MCP**: Check for MCP tools with names containing `ubcode` or `useblocks`. Use for pre-indexed data and link graph.
+3. **Raw file parsing**: Search for `ubproject.toml` or `conf.py` for configuration. Grep for need directives (`.. <type>::`) in RST/MD files. Parse options (`:id:`, `:status:`, `:links:`, extra_links). Build the link graph manually.
+
+Read `pharaoh.toml` for strictness level, workflow gates, traceability requirements, and codelinks settings.
+
+## Process
+
+### Step 1: Understand the Change
+
+Extract from the user's request:
+- **Target need ID(s)**: One or more need IDs. If described by title, resolve after data access.
+- **Nature of change**: Value change, addition, removal, or restructuring.
+- **Change description**: What changes and why.
+
+Clarify ambiguity with at most one round of questions.
+
+### Step 2: Get Project Data
+
+Detect the project and build the needs index. Present summary:
+
+```
+Project: <name> (<config source>)
+Types: <directive names>
+Links: <link type names>
+Data source: <tier used>
+Needs found: <count>
+Codelinks: <enabled/disabled/not configured>
+Strictness: <advisory/enforcing>
+```
+
+Resolve need IDs from descriptions if needed (title/content matching).
+
+### Step 3: Impact Analysis
+
+**Direct impact (1 hop)**: Find every need directly linked to the target through any link type and direction.
+
+**Transitive impact (full graph)**: BFS from directly impacted needs through all link types. Track distance from target. Use a visited set to handle cycles.
+
+**Code impact** (if codelinks enabled): For every affected need, search code files for codelink annotations (`# codelink: <ID>`, `// codelink: <ID>`, etc.).
+
+**Classify severity** for each affected item:
+- **Must update**: Content references the specific value being changed.
+- **Review needed**: Linked but impact unclear; content relates to the changed property without referencing the specific value.
+- **No change needed**: Linked but addresses a different concern entirely.
+
+### Step 4: Produce Change Document
+
+```
+## Change Document
+
+### Change Request
+- **Target**: <NEED_ID> (<title>)
+- **Change**: <description>
+- **Date**: <ISO 8601 date>
+
+### Direct Impact (1 hop)
+
+| Need ID | Type | Title | Link Type | Direction | Action |
+|---------|------|-------|-----------|-----------|--------|
+
+### Transitive Impact
+
+| Need ID | Type | Title | Distance | Path | Action |
+|---------|------|-------|----------|------|--------|
+
+### Code Impact
+
+| File | Location | Linked Need | Action |
+|------|----------|-------------|--------|
+
+### Summary
+- Needs requiring update: <count>
+- Needs requiring review: <count>
+- No change needed: <count>
+- Code files affected: <count>
+- Recommendation: <proceed / escalate / discuss>
+```
+
+**Recommendation**: Proceed if <= 5 must-update items and no safety-tagged needs affected. Escalate if safety/critical/regulatory-tagged needs are "Must update" or >10 items need update. Discuss if impact is ambiguous.
+
+### Step 5: Update Session State
+
+Write to `.pharaoh/session.json`:
+- Set `changes.<target_id>.change_analysis` to current timestamp.
+- Set `acknowledged` to `false` initially.
+
+### Step 6: Ask for Acknowledgment
+
+```
+Acknowledge this change analysis? Acknowledging allows proceeding to @pharaoh.author for the affected needs.
+```
+
+If acknowledged, set `changes.<target_id>.acknowledged = true` in session state.
+
+## Strictness Behavior
+
+This agent has **no prerequisites** and runs freely in both advisory and enforcing modes. However, its output gates `@pharaoh.author` in enforcing mode -- authoring requires an acknowledged change analysis.
+
+## Constraints
+
+1. Always trace ALL configured link types. Read the project's `extra_links` configuration.
+2. Handle circular links with a visited set. Report cycles.
+3. Support multi-project setups. Label cross-project needs.
+4. For large impact scopes (>50 needs), recommend escalation.
+5. Never modify need source files. This agent is read-only except for session state.

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

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

@@ -0,0 +1,10 @@
+---
+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
+
+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

@@ -0,0 +1,10 @@
+---
+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
+
+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.