From fd2e9eb2a65e0cbc58bb8b38710f31cf0a3e9319 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 15:03:07 +0200 Subject: [PATCH] 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. --- .../pharaoh.activity-diagram-draft.agent.md | 4 ++-- .../pharaoh.api-coverage-check.agent.md | 6 ++--- .github/agents/pharaoh.arch-draft.agent.md | 4 ++-- .github/agents/pharaoh.arch-review.agent.md | 4 ++-- .github/agents/pharaoh.audit-fanout.agent.md | 4 ++-- .../pharaoh.block-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.bootstrap.agent.md | 4 ++-- .github/agents/pharaoh.change.agent.md | 2 +- .../pharaoh.class-diagram-draft.agent.md | 4 ++-- .../pharaoh.component-diagram-draft.agent.md | 4 ++-- .../agents/pharaoh.context-gather.agent.md | 4 ++-- .github/agents/pharaoh.coverage-gap.agent.md | 4 ++-- .github/agents/pharaoh.decide.agent.md | 2 +- .../agents/pharaoh.decision-record.agent.md | 4 ++-- .../agents/pharaoh.decision-review.agent.md | 6 ++--- .../pharaoh.deployment-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.diagram-lint.agent.md | 4 ++-- .../agents/pharaoh.diagram-review.agent.md | 6 ++--- .../pharaoh.dispatch-signal-check.agent.md | 6 ++--- .github/agents/pharaoh.execute-plan.agent.md | 4 ++-- .../pharaoh.fault-tree-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.feat-balance.agent.md | 4 ++-- .../pharaoh.feat-component-extract.agent.md | 4 ++-- .../pharaoh.feat-draft-from-docs.agent.md | 4 ++-- .github/agents/pharaoh.feat-file-map.agent.md | 4 ++-- .../agents/pharaoh.feat-flow-extract.agent.md | 4 ++-- .github/agents/pharaoh.feat-review.agent.md | 6 ++--- .../agents/pharaoh.finding-record.agent.md | 4 ++-- .github/agents/pharaoh.flow.agent.md | 4 ++-- .github/agents/pharaoh.fmea-review.agent.md | 6 ++--- .github/agents/pharaoh.fmea.agent.md | 4 ++-- .github/agents/pharaoh.gate-advisor.agent.md | 6 ++--- .github/agents/pharaoh.id-allocate.agent.md | 4 ++-- .../pharaoh.id-convention-check.agent.md | 6 ++--- .../agents/pharaoh.lifecycle-check.agent.md | 4 ++-- .../pharaoh.link-completeness-check.agent.md | 6 ++--- .github/agents/pharaoh.mece.agent.md | 2 +- .../agents/pharaoh.output-validate.agent.md | 4 ++-- .../pharaoh.papyrus-non-empty-check.agent.md | 4 ++-- .github/agents/pharaoh.plan.agent.md | 2 +- .github/agents/pharaoh.process-audit.agent.md | 4 ++-- .github/agents/pharaoh.prose-migrate.agent.md | 4 ++-- .github/agents/pharaoh.quality-gate.agent.md | 4 ++-- .github/agents/pharaoh.release.agent.md | 2 +- .../pharaoh.reproducibility-check.agent.md | 6 ++--- .../pharaoh.req-code-grounding-check.agent.md | 6 ++--- .../pharaoh.req-codelink-annotate.agent.md | 4 ++-- .github/agents/pharaoh.req-draft.agent.md | 4 ++-- .github/agents/pharaoh.req-from-code.agent.md | 4 ++-- .../agents/pharaoh.req-regenerate.agent.md | 4 ++-- .github/agents/pharaoh.req-review.agent.md | 4 ++-- .../pharaoh.review-completeness.agent.md | 4 ++-- ...haraoh.self-review-coverage-check.agent.md | 6 ++--- .../pharaoh.sequence-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.setup.agent.md | 23 +++++++++++++++++-- .github/agents/pharaoh.spec.agent.md | 2 +- .../pharaoh.sphinx-extension-add.agent.md | 4 ++-- .../pharaoh.standard-conformance.agent.md | 4 ++-- .../pharaoh.state-diagram-draft.agent.md | 4 ++-- .../pharaoh.status-lifecycle-check.agent.md | 4 ++-- .../agents/pharaoh.tailor-bootstrap.agent.md | 4 ++-- ...aoh.tailor-code-grounding-filters.agent.md | 4 ++-- .github/agents/pharaoh.tailor-detect.agent.md | 4 ++-- .github/agents/pharaoh.tailor-fill.agent.md | 4 ++-- .github/agents/pharaoh.tailor-review.agent.md | 4 ++-- .github/agents/pharaoh.toctree-emit.agent.md | 4 ++-- .github/agents/pharaoh.trace.agent.md | 2 +- .../pharaoh.use-case-diagram-draft.agent.md | 6 ++--- .github/agents/pharaoh.vplan-draft.agent.md | 4 ++-- .github/agents/pharaoh.vplan-review.agent.md | 4 ++-- .github/agents/pharaoh.write-plan.agent.md | 4 ++-- .github/workflows/ci.yaml | 22 ++++++++++++++++++ 72 files changed, 189 insertions(+), 148 deletions(-) diff --git a/.github/agents/pharaoh.activity-diagram-draft.agent.md b/.github/agents/pharaoh.activity-diagram-draft.agent.md index cb40cfe..36bba5e 100644 --- a/.github/agents/pharaoh.activity-diagram-draft.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.api-coverage-check.agent.md b/.github/agents/pharaoh.api-coverage-check.agent.md index f76eb9c..0fac840 100644 --- a/.github/agents/pharaoh.api-coverage-check.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.arch-draft.agent.md b/.github/agents/pharaoh.arch-draft.agent.md index 36d408c..3f9b5e3 100644 --- a/.github/agents/pharaoh.arch-draft.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.arch-review.agent.md b/.github/agents/pharaoh.arch-review.agent.md index c46b8fb..ac6afb0 100644 --- a/.github/agents/pharaoh.arch-review.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.audit-fanout.agent.md b/.github/agents/pharaoh.audit-fanout.agent.md index e809101..c314f96 100644 --- a/.github/agents/pharaoh.audit-fanout.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.block-diagram-draft.agent.md b/.github/agents/pharaoh.block-diagram-draft.agent.md index 0436607..99e72ac 100644 --- a/.github/agents/pharaoh.block-diagram-draft.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.bootstrap.agent.md b/.github/agents/pharaoh.bootstrap.agent.md index bca421a..213249a 100644 --- a/.github/agents/pharaoh.bootstrap.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.change.agent.md b/.github/agents/pharaoh.change.agent.md index 1ed8190..df8fdf3 100644 --- a/.github/agents/pharaoh.change.agent.md +++ b/.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 diff --git a/.github/agents/pharaoh.class-diagram-draft.agent.md b/.github/agents/pharaoh.class-diagram-draft.agent.md index 7eef840..5911999 100644 --- a/.github/agents/pharaoh.class-diagram-draft.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.component-diagram-draft.agent.md b/.github/agents/pharaoh.component-diagram-draft.agent.md index b0bea11..e4bf231 100644 --- a/.github/agents/pharaoh.component-diagram-draft.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.context-gather.agent.md b/.github/agents/pharaoh.context-gather.agent.md index 24926d3..8f21d82 100644 --- a/.github/agents/pharaoh.context-gather.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.coverage-gap.agent.md b/.github/agents/pharaoh.coverage-gap.agent.md index ef820ca..b95341d 100644 --- a/.github/agents/pharaoh.coverage-gap.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.decide.agent.md b/.github/agents/pharaoh.decide.agent.md index 2b6938e..4e942fb 100644 --- a/.github/agents/pharaoh.decide.agent.md +++ b/.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 diff --git a/.github/agents/pharaoh.decision-record.agent.md b/.github/agents/pharaoh.decision-record.agent.md index 6b6b044..c7cccc6 100644 --- a/.github/agents/pharaoh.decision-record.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.decision-review.agent.md b/.github/agents/pharaoh.decision-review.agent.md index e644a61..35d3bb0 100644 --- a/.github/agents/pharaoh.decision-review.agent.md +++ b/.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. diff --git a/.github/agents/pharaoh.deployment-diagram-draft.agent.md b/.github/agents/pharaoh.deployment-diagram-draft.agent.md index 8e99724..b35581c 100644 --- a/.github/agents/pharaoh.deployment-diagram-draft.agent.md +++ b/.github/agents/pharaoh.deployment-diagram-draft.agent.md @@ -1,10 +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). +description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). 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). +Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). 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. diff --git a/.github/agents/pharaoh.diagram-lint.agent.md b/.github/agents/pharaoh.diagram-lint.agent.md index 4aa99bd..45014e4 100644 --- a/.github/agents/pharaoh.diagram-lint.agent.md +++ b/.github/agents/pharaoh.diagram-lint.agent.md @@ -1,5 +1,5 @@ --- -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. +description: Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files. handoffs: - label: Aggregate into quality gate agent: pharaoh.quality-gate @@ -8,6 +8,6 @@ handoffs: # @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. +Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files. 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. diff --git a/.github/agents/pharaoh.diagram-review.agent.md b/.github/agents/pharaoh.diagram-review.agent.md index 5b7d396..deb7695 100644 --- a/.github/agents/pharaoh.diagram-review.agent.md +++ b/.github/agents/pharaoh.diagram-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes. +description: Use when auditing a single diagram block (Mermaid or PlantUML) emitted by any diagram-emitting skill. Single review atom covering all diagram types — trace/caption/element-count/parser/required-elements checks plus LLM-judge axes for purpose clarity and granularity consistency. Per-type required-element checks dispatched based on `diagram_type` input. handoffs: [] --- # @pharaoh.diagram-review -Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes. +Use when auditing a single diagram block (Mermaid or PlantUML) emitted by any diagram-emitting skill. Single review atom covering all diagram types — trace/caption/element-count/parser/required-elements checks plus LLM-judge axes for purpose clarity and granularity consistency. Per-type required-element checks dispatched based on `diagram_type` input. -See [`skills/pharaoh-diagram-review/SKILL.md`](../../skills/pharaoh-diagram-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-diagram-review/SKILL.md`](../../skills/pharaoh-diagram-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.dispatch-signal-check.agent.md b/.github/agents/pharaoh.dispatch-signal-check.agent.md index 52d8c1e..60f80e4 100644 --- a/.github/agents/pharaoh.dispatch-signal-check.agent.md +++ b/.github/agents/pharaoh.dispatch-signal-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify declared execution_mode in plan.yaml matches observed artefacts in runs/. +description: Use when verifying that a plan's declared `execution_mode` matches observed subagent artefacts in `runs/`. Detects the "LLM-executor collapsed subagents into inline" failure class observed during dogfooding. One mechanical structural check. handoffs: [] --- # @pharaoh.dispatch-signal-check -Verify declared execution_mode in plan.yaml matches observed artefacts in runs/. +Use when verifying that a plan's declared `execution_mode` matches observed subagent artefacts in `runs/`. Detects the "LLM-executor collapsed subagents into inline" failure class observed during dogfooding. One mechanical structural check. -See [`skills/pharaoh-dispatch-signal-check/SKILL.md`](../../skills/pharaoh-dispatch-signal-check/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-dispatch-signal-check/SKILL.md`](../../skills/pharaoh-dispatch-signal-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.execute-plan.agent.md b/.github/agents/pharaoh.execute-plan.agent.md index 2c1cf46..2324022 100644 --- a/.github/agents/pharaoh.execute-plan.agent.md +++ b/.github/agents/pharaoh.execute-plan.agent.md @@ -1,10 +1,10 @@ --- -description: Use when executing a plan. +description: Use when executing a plan.yaml produced by pharaoh-write-plan. Reads the plan, runs each task (inline or via subagent dispatch), threads outputs between tasks per the ref grammar, validates outputs via pharaoh-output-validate, persists artefacts and report.yaml. Generic — the plan is the orchestrator, this skill is the engine. handoffs: [] --- # @pharaoh.execute-plan -Use when executing a plan. +Use when executing a plan.yaml produced by pharaoh-write-plan. Reads the plan, runs each task (inline or via subagent dispatch), threads outputs between tasks per the ref grammar, validates outputs via pharaoh-output-validate, persists artefacts and report.yaml. Generic — the plan is the orchestrator, this skill is the engine. 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. diff --git a/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md b/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md index e7ad53d..044a7ad 100644 --- a/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md +++ b/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md @@ -1,10 +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). +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). Typical ISO 26262 usage — Part 3 Hazard Analysis & Risk Assessment, and Part 5 supporting hardware architectural metrics. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). 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). +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). Typical ISO 26262 usage — Part 3 Hazard Analysis & Risk Assessment, and Part 5 supporting hardware architectural metrics. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). 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. diff --git a/.github/agents/pharaoh.feat-balance.agent.md b/.github/agents/pharaoh.feat-balance.agent.md index 3829768..fd28551 100644 --- a/.github/agents/pharaoh.feat-balance.agent.md +++ b/.github/agents/pharaoh.feat-balance.agent.md @@ -1,10 +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). +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). Reports health and suggestions; does not mutate. 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). +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). Reports health and suggestions; does not mutate. 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. diff --git a/.github/agents/pharaoh.feat-component-extract.agent.md b/.github/agents/pharaoh.feat-component-extract.agent.md index c29c37e..b3db215 100644 --- a/.github/agents/pharaoh.feat-component-extract.agent.md +++ b/.github/agents/pharaoh.feat-component-extract.agent.md @@ -1,10 +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. +description: Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. Walks import edges between the listed files and emits a Mermaid or PlantUML diagram whose output shape is compatible with pharaoh-component-diagram-draft. Does NOT hand-author nodes or edges; extraction is rule-based. 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. +Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. Walks import edges between the listed files and emits a Mermaid or PlantUML diagram whose output shape is compatible with pharaoh-component-diagram-draft. Does NOT hand-author nodes or edges; extraction is rule-based. 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. diff --git a/.github/agents/pharaoh.feat-draft-from-docs.agent.md b/.github/agents/pharaoh.feat-draft-from-docs.agent.md index 63216a1..d2c4477 100644 --- a/.github/agents/pharaoh.feat-draft-from-docs.agent.md +++ b/.github/agents/pharaoh.feat-draft-from-docs.agent.md @@ -1,10 +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. +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. Does NOT read source code. Does NOT emit component requirements. Does NOT map features to files — that is `pharaoh-feat-file-map`. 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. +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. Does NOT read source code. Does NOT emit component requirements. Does NOT map features to files — that is `pharaoh-feat-file-map`. 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. diff --git a/.github/agents/pharaoh.feat-file-map.agent.md b/.github/agents/pharaoh.feat-file-map.agent.md index 0680f3b..5726391 100644 --- a/.github/agents/pharaoh.feat-file-map.agent.md +++ b/.github/agents/pharaoh.feat-file-map.agent.md @@ -1,10 +1,10 @@ --- -description: Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. +description: Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. Reads the source tree, returns a YAML entry `{feat_id: {files: [...], rationale: "..."}}`. Does NOT read docs. Does NOT emit reqs. Does NOT create or modify source files. handoffs: [] --- # @pharaoh.feat-file-map -Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. +Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. Reads the source tree, returns a YAML entry `{feat_id: {files: [...], rationale: "..."}}`. Does NOT read docs. Does NOT emit reqs. Does NOT create or modify source files. 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. diff --git a/.github/agents/pharaoh.feat-flow-extract.agent.md b/.github/agents/pharaoh.feat-flow-extract.agent.md index 444be70..5d9cc2d 100644 --- a/.github/agents/pharaoh.feat-flow-extract.agent.md +++ b/.github/agents/pharaoh.feat-flow-extract.agent.md @@ -1,10 +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. +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. Walks the call graph up to a bounded depth and emits a Mermaid or PlantUML sequence diagram whose output shape matches pharaoh-sequence-diagram-draft. Complements pharaoh-feat-component-extract (static view); this is the dynamic view. 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. +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. Walks the call graph up to a bounded depth and emits a Mermaid or PlantUML sequence diagram whose output shape matches pharaoh-sequence-diagram-draft. Complements pharaoh-feat-component-extract (static view); this is the dynamic view. 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. diff --git a/.github/agents/pharaoh.feat-review.agent.md b/.github/agents/pharaoh.feat-review.agent.md index af64186..73e9d33 100644 --- a/.github/agents/pharaoh.feat-review.agent.md +++ b/.github/agents/pharaoh.feat-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single feature-level need against the generic feat review axes plus any project-specific addenda. +description: Use when auditing a single feature-level need (feat) against the generic feat review axes in `shared/checklists/feat.md` plus any per-project addenda in `.pharaoh/project/checklists/feat.md`. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes. Mirrors `pharaoh-req-review`'s shape for feat-level artefacts. handoffs: [] --- # @pharaoh.feat-review -Audit a single feature-level need against the generic feat review axes plus any project-specific addenda. +Use when auditing a single feature-level need (feat) against the generic feat review axes in `shared/checklists/feat.md` plus any per-project addenda in `.pharaoh/project/checklists/feat.md`. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes. Mirrors `pharaoh-req-review`'s shape for feat-level artefacts. -See [`skills/pharaoh-feat-review/SKILL.md`](../../skills/pharaoh-feat-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-feat-review/SKILL.md`](../../skills/pharaoh-feat-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.finding-record.agent.md b/.github/agents/pharaoh.finding-record.agent.md index 4da1519..35e2162 100644 --- a/.github/agents/pharaoh.finding-record.agent.md +++ b/.github/agents/pharaoh.finding-record.agent.md @@ -1,10 +1,10 @@ --- -description: Record an audit finding in the shared Papyrus workspace with deterministic dedup across concurrent subagents. +description: Use when recording an audit finding in the shared Papyrus workspace with automatic dedup. Uses deterministic ID to ensure the same {category, subject_id} tuple never appears twice across concurrent subagents. Returns {action: wrote|duplicate, papyrus_id}. handoffs: [] --- # @pharaoh.finding-record -Record an audit finding in the shared Papyrus workspace with deterministic dedup across concurrent subagents. +Use when recording an audit finding in the shared Papyrus workspace with automatic dedup. Uses deterministic ID to ensure the same {category, subject_id} tuple never appears twice across concurrent subagents. Returns {action: wrote|duplicate, papyrus_id}. See [`skills/pharaoh-finding-record/SKILL.md`](../../skills/pharaoh-finding-record/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.flow.agent.md b/.github/agents/pharaoh.flow.agent.md index f670320..ac61e8d 100644 --- a/.github/agents/pharaoh.flow.agent.md +++ b/.github/agents/pharaoh.flow.agent.md @@ -1,10 +1,10 @@ --- -description: Orchestrate the full V-model chain — requirement, architecture, verification plan, FMEA — with review passes. +description: Use when orchestrating the full V-model chain for one feature context — requirement → architecture element → verification plan → FMEA, each with a review pass. Invokes pharaoh-req-draft, pharaoh-req-review, pharaoh-arch-draft, pharaoh-arch-review, pharaoh-vplan-draft, pharaoh-vplan-review, pharaoh-fmea in sequence. handoffs: [] --- # @pharaoh.flow -Orchestrate the full V-model chain — requirement, architecture, verification plan, FMEA — with review passes. +Use when orchestrating the full V-model chain for one feature context — requirement → architecture element → verification plan → FMEA, each with a review pass. Invokes pharaoh-req-draft, pharaoh-req-review, pharaoh-arch-draft, pharaoh-arch-review, pharaoh-vplan-draft, pharaoh-vplan-review, pharaoh-fmea in sequence. See [`skills/pharaoh-flow/SKILL.md`](../../skills/pharaoh-flow/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.fmea-review.agent.md b/.github/agents/pharaoh.fmea-review.agent.md index 6768550..9f8c623 100644 --- a/.github/agents/pharaoh.fmea-review.agent.md +++ b/.github/agents/pharaoh.fmea-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness. +description: Use when auditing a single FMEA entry (failure-mode row) against the generic FMEA review axes in `shared/checklists/fmea.md` plus per-project addenda. Checks severity/occurrence/detection scales, RPN computation, cause/effect well-formedness, traceability to the analyzed artefact. Emits structured findings JSON. handoffs: [] --- # @pharaoh.fmea-review -Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness. +Use when auditing a single FMEA entry (failure-mode row) against the generic FMEA review axes in `shared/checklists/fmea.md` plus per-project addenda. Checks severity/occurrence/detection scales, RPN computation, cause/effect well-formedness, traceability to the analyzed artefact. Emits structured findings JSON. -See [`skills/pharaoh-fmea-review/SKILL.md`](../../skills/pharaoh-fmea-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-fmea-review/SKILL.md`](../../skills/pharaoh-fmea-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.fmea.agent.md b/.github/agents/pharaoh.fmea.agent.md index f990fa0..9b3f4b4 100644 --- a/.github/agents/pharaoh.fmea.agent.md +++ b/.github/agents/pharaoh.fmea.agent.md @@ -1,10 +1,10 @@ --- -description: Derive a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. +description: Use when deriving a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. Emits structured JSON with cause, effect, severity (1-10), occurrence (1-10), detection (1-10), and RPN. handoffs: [] --- # @pharaoh.fmea -Derive a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. +Use when deriving a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. Emits structured JSON with cause, effect, severity (1-10), occurrence (1-10), detection (1-10), and RPN. See [`skills/pharaoh-fmea/SKILL.md`](../../skills/pharaoh-fmea/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.gate-advisor.agent.md b/.github/agents/pharaoh.gate-advisor.agent.md index 4c9c63b..0991f5c 100644 --- a/.github/agents/pharaoh.gate-advisor.agent.md +++ b/.github/agents/pharaoh.gate-advisor.agent.md @@ -1,10 +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. +description: Use when reading a project's `pharaoh.toml` to report which phased-enablement ladder step is the recommended next gate to switch on. Single mechanical advisory check — parses five flags (`strictness`, `require_verification`, `require_change_analysis`, `require_mece_on_release`, `codelinks.enabled`), walks the fixed ladder in order, and emits the first unmet step plus its blocker note. Read-only; never edits `pharaoh.toml`. 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. +Use when reading a project's `pharaoh.toml` to report which phased-enablement ladder step is the recommended next gate to switch on. Single mechanical advisory check — parses five flags (`strictness`, `require_verification`, `require_change_analysis`, `require_mece_on_release`, `codelinks.enabled`), walks the fixed ladder in order, and emits the first unmet step plus its blocker note. Read-only; never edits `pharaoh.toml`. -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. +See [`skills/pharaoh-gate-advisor/SKILL.md`](../../skills/pharaoh-gate-advisor/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.id-allocate.agent.md b/.github/agents/pharaoh.id-allocate.agent.md index c2d23d7..bb80390 100644 --- a/.github/agents/pharaoh.id-allocate.agent.md +++ b/.github/agents/pharaoh.id-allocate.agent.md @@ -1,10 +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. +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. Each subagent receives its pre-allocated pool and emits only from that pool, so parallel agents cannot collide on stem choice. Does NOT invoke emitters, does NOT write RST. 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. +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. Each subagent receives its pre-allocated pool and emits only from that pool, so parallel agents cannot collide on stem choice. Does NOT invoke emitters, does NOT write RST. 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. diff --git a/.github/agents/pharaoh.id-convention-check.agent.md b/.github/agents/pharaoh.id-convention-check.agent.md index d2af8bf..f8e2ff2 100644 --- a/.github/agents/pharaoh.id-convention-check.agent.md +++ b/.github/agents/pharaoh.id-convention-check.agent.md @@ -1,10 +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. +description: Use when verifying that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Single mechanical structural check — applies the tailored per-type regex, emits a list of violations. Does NOT auto-detect how many schemes coexist — scheme policy is the tailoring author's responsibility (declare an alternation to allow multiple forms). 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. +Use when verifying that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Single mechanical structural check — applies the tailored per-type regex, emits a list of violations. Does NOT auto-detect how many schemes coexist — scheme policy is the tailoring author's responsibility (declare an alternation to allow multiple forms). -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. +See [`skills/pharaoh-id-convention-check/SKILL.md`](../../skills/pharaoh-id-convention-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.lifecycle-check.agent.md b/.github/agents/pharaoh.lifecycle-check.agent.md index 9122660..b7474ef 100644 --- a/.github/agents/pharaoh.lifecycle-check.agent.md +++ b/.github/agents/pharaoh.lifecycle-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify a sphinx-needs artefact's lifecycle state and the legality of a requested state transition. +description: Use when verifying a sphinx-needs artefact's current lifecycle state and the legality of a requested state transition per the project's workflows.yaml state machine. handoffs: [] --- # @pharaoh.lifecycle-check -Verify a sphinx-needs artefact's lifecycle state and the legality of a requested state transition. +Use when verifying a sphinx-needs artefact's current lifecycle state and the legality of a requested state transition per the project's workflows.yaml state machine. See [`skills/pharaoh-lifecycle-check/SKILL.md`](../../skills/pharaoh-lifecycle-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.link-completeness-check.agent.md b/.github/agents/pharaoh.link-completeness-check.agent.md index e067e80..6d91804 100644 --- a/.github/agents/pharaoh.link-completeness-check.agent.md +++ b/.github/agents/pharaoh.link-completeness-check.agent.md @@ -1,10 +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. +description: Use when verifying outgoing-link coverage across a full needs.json graph. For each declared link type in `artefact-catalog.yaml`, confirms every need of the governed type carries a non-empty value AND every target id resolves to an existing need. Closes the "catalogue declares `verifies` required but half the reqs ship without it" failure class. 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. +Use when verifying outgoing-link coverage across a full needs.json graph. For each declared link type in `artefact-catalog.yaml`, confirms every need of the governed type carries a non-empty value AND every target id resolves to an existing need. Closes the "catalogue declares `verifies` required but half the reqs ship without it" failure class. -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. +See [`skills/pharaoh-link-completeness-check/SKILL.md`](../../skills/pharaoh-link-completeness-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.mece.agent.md b/.github/agents/pharaoh.mece.agent.md index 1c5e41c..ec4d116 100644 --- a/.github/agents/pharaoh.mece.agent.md +++ b/.github/agents/pharaoh.mece.agent.md @@ -1,5 +1,5 @@ --- -description: Check for gaps, redundancies, and inconsistencies in sphinx-needs requirements. Validates traceability completeness. +description: Use when checking for gaps, redundancies, and inconsistencies in sphinx-needs requirements, or validating traceability completeness handoffs: - label: Trace a Need agent: pharaoh.trace diff --git a/.github/agents/pharaoh.output-validate.agent.md b/.github/agents/pharaoh.output-validate.agent.md index 331ad1f..bfa1914 100644 --- a/.github/agents/pharaoh.output-validate.agent.md +++ b/.github/agents/pharaoh.output-validate.agent.md @@ -1,10 +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). +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). Returns {valid, errors, parsed, recovery}. Callers gate subagent output through this before writing anything to disk. 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). +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). Returns {valid, errors, parsed, recovery}. Callers gate subagent output through this before writing anything to disk. 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. diff --git a/.github/agents/pharaoh.papyrus-non-empty-check.agent.md b/.github/agents/pharaoh.papyrus-non-empty-check.agent.md index 4e02bf7..712d563 100644 --- a/.github/agents/pharaoh.papyrus-non-empty-check.agent.md +++ b/.github/agents/pharaoh.papyrus-non-empty-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify that a Papyrus workspace received at least N writes during a plan run. +description: Use when verifying that a Papyrus workspace actually received writes during a plan run. Single mechanical check — counts directives across `.papyrus/memory/*.rst` and returns pass/fail against a configured minimum. Wired into `pharaoh-quality-gate` to detect the "LLM-executor skipped the atomic Papyrus writes" failure class observed in prior dogfooding. handoffs: [] --- # @pharaoh.papyrus-non-empty-check -Verify that a Papyrus workspace received at least N writes during a plan run. +Use when verifying that a Papyrus workspace actually received writes during a plan run. Single mechanical check — counts directives across `.papyrus/memory/*.rst` and returns pass/fail against a configured minimum. Wired into `pharaoh-quality-gate` to detect the "LLM-executor skipped the atomic Papyrus writes" failure class observed in prior dogfooding. 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. diff --git a/.github/agents/pharaoh.plan.agent.md b/.github/agents/pharaoh.plan.agent.md index 8ec0bb7..db2b52f 100644 --- a/.github/agents/pharaoh.plan.agent.md +++ b/.github/agents/pharaoh.plan.agent.md @@ -1,5 +1,5 @@ --- -description: Break requirement changes into structured implementation tasks with workflow enforcement and dependency ordering. +description: Use when breaking requirement changes into structured implementation tasks with workflow enforcement and dependency ordering handoffs: - label: Start Change Analysis agent: pharaoh.change diff --git a/.github/agents/pharaoh.process-audit.agent.md b/.github/agents/pharaoh.process-audit.agent.md index 69e01de..3911cc0 100644 --- a/.github/agents/pharaoh.process-audit.agent.md +++ b/.github/agents/pharaoh.process-audit.agent.md @@ -1,10 +1,10 @@ --- -description: Run a full-corpus audit across all gap categories plus cross-artefact consistency checks. +description: Use when running a full-corpus audit against a sphinx-needs project. Orchestrates pharaoh-coverage-gap across all gap categories plus cross-artefact consistency checks. Emits a prioritised gap report. handoffs: [] --- # @pharaoh.process-audit -Run a full-corpus audit across all gap categories plus cross-artefact consistency checks. +Use when running a full-corpus audit against a sphinx-needs project. Orchestrates pharaoh-coverage-gap across all gap categories plus cross-artefact consistency checks. Emits a prioritised gap report. See [`skills/pharaoh-process-audit/SKILL.md`](../../skills/pharaoh-process-audit/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.prose-migrate.agent.md b/.github/agents/pharaoh.prose-migrate.agent.md index db1ab43..de450d1 100644 --- a/.github/agents/pharaoh.prose-migrate.agent.md +++ b/.github/agents/pharaoh.prose-migrate.agent.md @@ -1,10 +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. +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. Produces a sentence-by-sentence migration proposal — keep-as-user-guide, merge-into-feat-body, discard. Does NOT overwrite anything; the caller applies the proposal manually. 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. +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. Produces a sentence-by-sentence migration proposal — keep-as-user-guide, merge-into-feat-body, discard. Does NOT overwrite anything; the caller applies the proposal manually. 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. diff --git a/.github/agents/pharaoh.quality-gate.agent.md b/.github/agents/pharaoh.quality-gate.agent.md index 95a52fc..d500423 100644 --- a/.github/agents/pharaoh.quality-gate.agent.md +++ b/.github/agents/pharaoh.quality-gate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). +description: Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). Consumes an aggregated review+mece+coverage summary plus a gate spec; returns pass/fail with named breaches. Never produces summaries itself — thin gate layer over upstream atomic checkers. handoffs: [] --- # @pharaoh.quality-gate -Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). +Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). Consumes an aggregated review+mece+coverage summary plus a gate spec; returns pass/fail with named breaches. Never produces summaries itself — thin gate layer over upstream atomic checkers. 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. diff --git a/.github/agents/pharaoh.release.agent.md b/.github/agents/pharaoh.release.agent.md index 03d131c..089e004 100644 --- a/.github/agents/pharaoh.release.agent.md +++ b/.github/agents/pharaoh.release.agent.md @@ -1,5 +1,5 @@ --- -description: Prepare a release by generating changelogs from requirements, release summaries, and traceability coverage metrics. +description: Use when preparing a release, generating changelogs from requirements, or summarizing requirement changes for version management handoffs: - label: MECE Check agent: pharaoh.mece diff --git a/.github/agents/pharaoh.reproducibility-check.agent.md b/.github/agents/pharaoh.reproducibility-check.agent.md index ee77bd2..a42da34 100644 --- a/.github/agents/pharaoh.reproducibility-check.agent.md +++ b/.github/agents/pharaoh.reproducibility-check.agent.md @@ -1,10 +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`). +description: Use when diffing 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 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`). +Use when diffing 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 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. +See [`skills/pharaoh-reproducibility-check/SKILL.md`](../../skills/pharaoh-reproducibility-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-code-grounding-check.agent.md b/.github/agents/pharaoh.req-code-grounding-check.agent.md index f188291..c8d4075 100644 --- a/.github/agents/pharaoh.req-code-grounding-check.agent.md +++ b/.github/agents/pharaoh.req-code-grounding-check.agent.md @@ -1,10 +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. +description: Use when verifying a single drafted requirement against the source file it cites via `:source_doc:`. Single mechanical fidelity check — compares the CREQ's claims about exceptions, triggers, types, structural symbols, backtick-quoted identifiers, grounding density, adjectives, quantifiers, and branch count against the cited source, returning per-axis findings JSON. Complements `pharaoh-req-review` (which grades prose quality) with code-grounded axes. 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. +Use when verifying a single drafted requirement against the source file it cites via `:source_doc:`. Single mechanical fidelity check — compares the CREQ's claims about exceptions, triggers, types, structural symbols, backtick-quoted identifiers, grounding density, adjectives, quantifiers, and branch count against the cited source, returning per-axis findings JSON. Complements `pharaoh-req-review` (which grades prose quality) with code-grounded axes. -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. +See [`skills/pharaoh-req-code-grounding-check/SKILL.md`](../../skills/pharaoh-req-code-grounding-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-codelink-annotate.agent.md b/.github/agents/pharaoh.req-codelink-annotate.agent.md index 004eb8c..c4f79b1 100644 --- a/.github/agents/pharaoh.req-codelink-annotate.agent.md +++ b/.github/agents/pharaoh.req-codelink-annotate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. +description: Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. Two modes — `codelinks` (sphinx-codelinks-compatible multi-field `@ title, id, type, [links]` form; the comment IS the need) and `backref` (minimal `@req ID: title` pointer back to an RST-hosted need). Mode is tailored via `ubproject.toml` / `pharaoh.toml`, not hardcoded. handoffs: [] --- # @pharaoh.req-codelink-annotate -Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. +Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. Two modes — `codelinks` (sphinx-codelinks-compatible multi-field `@ title, id, type, [links]` form; the comment IS the need) and `backref` (minimal `@req ID: title` pointer back to an RST-hosted need). Mode is tailored via `ubproject.toml` / `pharaoh.toml`, not hardcoded. See [`skills/pharaoh-req-codelink-annotate/SKILL.md`](../../skills/pharaoh-req-codelink-annotate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-draft.agent.md b/.github/agents/pharaoh.req-draft.agent.md index 0c56ffd..1e34763 100644 --- a/.github/agents/pharaoh.req-draft.agent.md +++ b/.github/agents/pharaoh.req-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single sphinx-needs requirement from a feature description. +description: Use when drafting a single sphinx-needs requirement from a feature description. Produces a new RST directive block with ID, status=draft, and a single shall-clause body, linking to a parent requirement or workflow per the project's artefact-catalog. handoffs: [] --- # @pharaoh.req-draft -Draft a single sphinx-needs requirement from a feature description. +Use when drafting a single sphinx-needs requirement from a feature description. Produces a new RST directive block with ID, status=draft, and a single shall-clause body, linking to a parent requirement or workflow per the project's artefact-catalog. See [`skills/pharaoh-req-draft/SKILL.md`](../../skills/pharaoh-req-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-from-code.agent.md b/.github/agents/pharaoh.req-from-code.agent.md index 848345a..9e7bb93 100644 --- a/.github/agents/pharaoh.req-from-code.agent.md +++ b/.github/agents/pharaoh.req-from-code.agent.md @@ -1,10 +1,10 @@ --- -description: Read one source file and emit comp_req directives describing its observable behavior, coordinating canonical names via Papyrus. +description: Use when reading one source file and emitting one or more requirement RST directives (typed by `target_level`) describing the observable behavior in that file. Queries shared Papyrus for canonical terms before naming concepts; writes newly surfaced concepts back. Does not draft architecture, plans, or FMEA. handoffs: [] --- # @pharaoh.req-from-code -Read one source file and emit comp_req directives describing its observable behavior, coordinating canonical names via Papyrus. +Use when reading one source file and emitting one or more requirement RST directives (typed by `target_level`) describing the observable behavior in that file. Queries shared Papyrus for canonical terms before naming concepts; writes newly surfaced concepts back. Does not draft architecture, plans, or FMEA. See [`skills/pharaoh-req-from-code/SKILL.md`](../../skills/pharaoh-req-from-code/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-regenerate.agent.md b/.github/agents/pharaoh.req-regenerate.agent.md index e0d48e9..28f7407 100644 --- a/.github/agents/pharaoh.req-regenerate.agent.md +++ b/.github/agents/pharaoh.req-regenerate.agent.md @@ -1,10 +1,10 @@ --- -description: Regenerate a single sphinx-needs requirement to address findings from a prior review. +description: Use when regenerating a single sphinx-needs requirement to address findings from pharaoh-req-review. Consumes the original RST + findings JSON, emits a revised RST directive that passes the flagged axes. handoffs: [] --- # @pharaoh.req-regenerate -Regenerate a single sphinx-needs requirement to address findings from a prior review. +Use when regenerating a single sphinx-needs requirement to address findings from pharaoh-req-review. Consumes the original RST + findings JSON, emits a revised RST directive that passes the flagged axes. See [`skills/pharaoh-req-regenerate/SKILL.md`](../../skills/pharaoh-req-regenerate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-review.agent.md b/.github/agents/pharaoh.req-review.agent.md index f33ff28..dabf554 100644 --- a/.github/agents/pharaoh.req-review.agent.md +++ b/.github/agents/pharaoh.req-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single sphinx-needs requirement against the ISO 26262 Part 8 §6 axes. +description: Use when auditing a single sphinx-needs requirement against the 11 ISO 26262 Part 8 §6 axes. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes, with action items for any failure. handoffs: [] --- # @pharaoh.req-review -Audit a single sphinx-needs requirement against the ISO 26262 Part 8 §6 axes. +Use when auditing a single sphinx-needs requirement against the 11 ISO 26262 Part 8 §6 axes. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes, with action items for any failure. See [`skills/pharaoh-req-review/SKILL.md`](../../skills/pharaoh-req-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.review-completeness.agent.md b/.github/agents/pharaoh.review-completeness.agent.md index 2873634..df8be0e 100644 --- a/.github/agents/pharaoh.review-completeness.agent.md +++ b/.github/agents/pharaoh.review-completeness.agent.md @@ -1,10 +1,10 @@ --- -description: Inspect needs for review / approval-chain completeness; flag missing reviewer / approved_by fields. +description: Use when inspecting one or more needs for review / approval-chain completeness. Flags needs missing required :reviewer: or :approved_by: fields per the project's artefact catalog. Emits one finding per incomplete need via pharaoh-finding-record. handoffs: [] --- # @pharaoh.review-completeness -Inspect needs for review / approval-chain completeness; flag missing reviewer / approved_by fields. +Use when inspecting one or more needs for review / approval-chain completeness. Flags needs missing required :reviewer: or :approved_by: fields per the project's artefact catalog. Emits one finding per incomplete need via pharaoh-finding-record. See [`skills/pharaoh-review-completeness/SKILL.md`](../../skills/pharaoh-review-completeness/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.self-review-coverage-check.agent.md b/.github/agents/pharaoh.self-review-coverage-check.agent.md index 92beffa..e93ca48 100644 --- a/.github/agents/pharaoh.self-review-coverage-check.agent.md +++ b/.github/agents/pharaoh.self-review-coverage-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify every drafted artefact in runs/ has a matching review JSON. +description: Use when verifying that every artefact emitted during a plan run received a matching review. For every drafted artefact in `runs/`, confirms a matching `_review.json` exists and is non-empty. Closes the "draft emitted but review was skipped" failure class. handoffs: [] --- # @pharaoh.self-review-coverage-check -Verify every drafted artefact in runs/ has a matching review JSON. +Use when verifying that every artefact emitted during a plan run received a matching review. For every drafted artefact in `runs/`, confirms a matching `_review.json` exists and is non-empty. Closes the "draft emitted but review was skipped" failure class. -See [`skills/pharaoh-self-review-coverage-check/SKILL.md`](../../skills/pharaoh-self-review-coverage-check/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-self-review-coverage-check/SKILL.md`](../../skills/pharaoh-self-review-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.sequence-diagram-draft.agent.md b/.github/agents/pharaoh.sequence-diagram-draft.agent.md index 6fd0ae8..666e39c 100644 --- a/.github/agents/pharaoh.sequence-diagram-draft.agent.md +++ b/.github/agents/pharaoh.sequence-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. +description: Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. Renderer tailored via `pharaoh.toml`. Does NOT emit component, class, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.sequence-diagram-draft -Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. +Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. Renderer tailored via `pharaoh.toml`. Does NOT emit component, class, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-sequence-diagram-draft/SKILL.md`](../../skills/pharaoh-sequence-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.setup.agent.md b/.github/agents/pharaoh.setup.agent.md index 9ff2517..e72a89e 100644 --- a/.github/agents/pharaoh.setup.agent.md +++ b/.github/agents/pharaoh.setup.agent.md @@ -1,5 +1,5 @@ --- -description: Scaffold Pharaoh into a sphinx-needs project. Detects project structure, generates pharaoh.toml, installs Copilot agents, and recommends tooling. +description: Use when setting up Pharaoh in a sphinx-needs project for the first time, scaffolding Copilot agents, or reconfiguring project detection handoffs: - label: Run MECE Check agent: pharaoh.mece @@ -67,7 +67,26 @@ Data access: ### Step 3: Configure .gitignore -Add `.pharaoh/` to `.gitignore` if not already present. Create `.gitignore` if needed. +`.pharaoh/` contains a mix of committed tailoring and ephemeral run state. Ignoring the whole tree is wrong — it hides `.pharaoh/project/` tailoring which IS shared across the team. Ignore only the ephemeral subpaths: + +| Path | Purpose | Commit? | +| ----------------------- | -------------------------------------------------------- | ------- | +| `.pharaoh/project/` | Tailoring: workflows, id-conventions, artefact-catalog, checklists | **yes** | +| `.pharaoh/runs/` | `pharaoh-execute-plan` run artefacts (report.yaml, staged RST) | no | +| `.pharaoh/plans/` | plan.yaml files emitted by `pharaoh-write-plan` | no | +| `.pharaoh/session.json` | Session / gate state | no | +| `.pharaoh/cache/` | Derived caches | no | + +Entries to add (create `.gitignore` if missing): + +``` +.pharaoh/runs/ +.pharaoh/plans/ +.pharaoh/session.json +.pharaoh/cache/ +``` + +If `.gitignore` already contains a bare `.pharaoh/` (or `.pharaoh`) line, leave it alone and warn the user that the wide form hides `.pharaoh/project/` tailoring which should be committed; recommend narrowing to the four ephemeral entries above. Do not auto-migrate — respect user control. ### Step 4: Recommend Tooling diff --git a/.github/agents/pharaoh.spec.agent.md b/.github/agents/pharaoh.spec.agent.md index 13e89a8..a3b87b5 100644 --- a/.github/agents/pharaoh.spec.agent.md +++ b/.github/agents/pharaoh.spec.agent.md @@ -1,5 +1,5 @@ --- -description: Generate a Superpowers-compatible spec and plan document from sphinx-needs requirements, bridging requirements to implementation. +description: Use when generating a Superpowers-compatible spec and plan document from sphinx-needs requirements, bridging requirements to implementation handoffs: - label: Execute Plan agent: pharaoh.plan diff --git a/.github/agents/pharaoh.sphinx-extension-add.agent.md b/.github/agents/pharaoh.sphinx-extension-add.agent.md index 67ceb53..9f9e20c 100644 --- a/.github/agents/pharaoh.sphinx-extension-add.agent.md +++ b/.github/agents/pharaoh.sphinx-extension-add.agent.md @@ -1,10 +1,10 @@ --- -description: Idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. +description: Use when you need to idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. Invoked by plans produced by pharaoh-write-plan when a diagram-emitting task requires a renderer extension that `conf.py` does not yet load. Does NOT emit RST. Does NOT build. handoffs: [] --- # @pharaoh.sphinx-extension-add -Add sphinx extensions (e.g. `sphinxcontrib.mermaid`, `sphinxcontrib.plantuml`, `myst_parser`) to a project's `conf.py` extensions list. Idempotent: noop when all requested extensions are already loaded. Optionally installs the corresponding pypi packages via the detected package manager (rye / uv / poetry / pdm / pip-venv). Typically inserted into a plan by `pharaoh.write-plan` as a prerequisite to diagram-emitting tasks when `conf.py` lacks the required renderer extension. +Use when you need to idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. Invoked by plans produced by pharaoh-write-plan when a diagram-emitting task requires a renderer extension that `conf.py` does not yet load. Does NOT emit RST. Does NOT build. See [`skills/pharaoh-sphinx-extension-add/SKILL.md`](../../skills/pharaoh-sphinx-extension-add/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.standard-conformance.agent.md b/.github/agents/pharaoh.standard-conformance.agent.md index 17ea5f7..ae0163c 100644 --- a/.github/agents/pharaoh.standard-conformance.agent.md +++ b/.github/agents/pharaoh.standard-conformance.agent.md @@ -1,10 +1,10 @@ --- -description: Evaluate a single artefact against one regulatory standard (ISO 26262, ASPICE, ISO/SAE 21434). +description: Use when evaluating a single sphinx-needs artefact against one regulatory standard (ISO 26262-8 §6, ASPICE 4.0, ISO/SAE 21434). Emits per-indicator findings JSON with pass/fail on mechanizable indicators and 0-3 scores on subjective ones. handoffs: [] --- # @pharaoh.standard-conformance -Evaluate a single artefact against one regulatory standard (ISO 26262, ASPICE, ISO/SAE 21434). +Use when evaluating a single sphinx-needs artefact against one regulatory standard (ISO 26262-8 §6, ASPICE 4.0, ISO/SAE 21434). Emits per-indicator findings JSON with pass/fail on mechanizable indicators and 0-3 scores on subjective ones. See [`skills/pharaoh-standard-conformance/SKILL.md`](../../skills/pharaoh-standard-conformance/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.state-diagram-draft.agent.md b/.github/agents/pharaoh.state-diagram-draft.agent.md index 652dc24..ec261c4 100644 --- a/.github/agents/pharaoh.state-diagram-draft.agent.md +++ b/.github/agents/pharaoh.state-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. +description: Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or class diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.state-diagram-draft -Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. +Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or class diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-state-diagram-draft/SKILL.md`](../../skills/pharaoh-state-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.status-lifecycle-check.agent.md b/.github/agents/pharaoh.status-lifecycle-check.agent.md index 935ba38..f04f403 100644 --- a/.github/agents/pharaoh.status-lifecycle-check.agent.md +++ b/.github/agents/pharaoh.status-lifecycle-check.agent.md @@ -1,5 +1,5 @@ --- -description: Release-gate check over a sphinx-needs corpus — counts needs still in the `draft` bucket (per workflows.yaml) and returns binary pass/fail when `enforce=true`. Advisory mode reports counts without failing. +description: Use when running a release-gate check over a full sphinx-needs corpus to confirm that zero needs remain in the initial `draft` status. Single mechanical binary gate — aggregates `status` across every need in `needs.json`, compares against the initial-state declaration in `workflows.yaml`, and returns pass/fail plus per-status counts. Advisory by default (pre-release development passes); release pipelines override `enforce=true` so any draft blocks the gate. handoffs: - label: Aggregate into quality gate agent: pharaoh.quality-gate @@ -8,6 +8,6 @@ handoffs: # @pharaoh.status-lifecycle-check -Aggregate `status` across every need in `needs.json` against the `initial_state` declared in `workflows.yaml`. Binary release gate — under `enforce=true`, zero drafts pass, one draft fails. Under `enforce=false` (default), the findings are reported without failing so pre-release development is unblocked. Distinct from `pharaoh-lifecycle-check`, which evaluates per-need transition legality against `requires:` prerequisites. +Use when running a release-gate check over a full sphinx-needs corpus to confirm that zero needs remain in the initial `draft` status. Single mechanical binary gate — aggregates `status` across every need in `needs.json`, compares against the initial-state declaration in `workflows.yaml`, and returns pass/fail plus per-status counts. Advisory by default (pre-release development passes); release pipelines override `enforce=true` so any draft blocks the gate. See [`skills/pharaoh-status-lifecycle-check/SKILL.md`](../../skills/pharaoh-status-lifecycle-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-bootstrap.agent.md b/.github/agents/pharaoh.tailor-bootstrap.agent.md index fc6465e..2e37a48 100644 --- a/.github/agents/pharaoh.tailor-bootstrap.agent.md +++ b/.github/agents/pharaoh.tailor-bootstrap.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows. +description: Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows.yaml, id-conventions.yaml, artefact-catalog.yaml, and per-type checklists — without requiring any needs to exist. Complements pharaoh-tailor-detect which requires ≥10 needs. handoffs: [] --- # @pharaoh.tailor-bootstrap -Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows. +Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows.yaml, id-conventions.yaml, artefact-catalog.yaml, and per-type checklists — without requiring any needs to exist. Complements pharaoh-tailor-detect which requires ≥10 needs. See [`skills/pharaoh-tailor-bootstrap/SKILL.md`](../../skills/pharaoh-tailor-bootstrap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md b/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md index b17d90c..f2f5bb6 100644 --- a/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md +++ b/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md @@ -1,10 +1,10 @@ --- -description: Detect language + CLI framework + config-default idiom in a project source tree and emit a code-grounding-filters.yaml wiring the four parameterised filter strategies to the detected stack. +description: Use when authoring a project's `code-grounding-filters.yaml` from observed stack conventions. Detects language + CLI framework + config-object style in the project source tree and emits a tailoring YAML populated with the four parameterised filter strategies. Does not invoke `pharaoh-req-code-grounding-check`; purely produces tailoring. handoffs: [] --- # @pharaoh.tailor-code-grounding-filters -Detect language + CLI framework + config-default idiom in a project source tree and emit a code-grounding-filters.yaml wiring the four parameterised filter strategies to the detected stack. +Use when authoring a project's `code-grounding-filters.yaml` from observed stack conventions. Detects language + CLI framework + config-object style in the project source tree and emits a tailoring YAML populated with the four parameterised filter strategies. Does not invoke `pharaoh-req-code-grounding-check`; purely produces tailoring. See [`skills/pharaoh-tailor-code-grounding-filters/SKILL.md`](../../skills/pharaoh-tailor-code-grounding-filters/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-detect.agent.md b/.github/agents/pharaoh.tailor-detect.agent.md index 233a42d..680f063 100644 --- a/.github/agents/pharaoh.tailor-detect.agent.md +++ b/.github/agents/pharaoh.tailor-detect.agent.md @@ -1,10 +1,10 @@ --- -description: Inspect a sphinx-needs project and emit a structured report of detected conventions. +description: Use when inspecting a sphinx-needs project to emit a structured report of detected conventions — prefixes, ID regex candidates, separator, lifecycle states, artefact types with observed required/optional fields. Does NOT author tailoring files (see pharaoh-tailor-fill). handoffs: [] --- # @pharaoh.tailor-detect -Inspect a sphinx-needs project and emit a structured report of detected conventions. +Use when inspecting a sphinx-needs project to emit a structured report of detected conventions — prefixes, ID regex candidates, separator, lifecycle states, artefact types with observed required/optional fields. Does NOT author tailoring files (see pharaoh-tailor-fill). See [`skills/pharaoh-tailor-detect/SKILL.md`](../../skills/pharaoh-tailor-detect/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-fill.agent.md b/.github/agents/pharaoh.tailor-fill.agent.md index 92f35f3..11afcd1 100644 --- a/.github/agents/pharaoh.tailor-fill.agent.md +++ b/.github/agents/pharaoh.tailor-fill.agent.md @@ -1,10 +1,10 @@ --- -description: Author .pharaoh/project/ tailoring files from a detected-conventions report. +description: Use when authoring the .pharaoh/project/ tailoring files (id-conventions.yaml, workflows.yaml, artefact-catalog.yaml, checklists/requirement.md) from detected-conventions JSON produced by pharaoh-tailor-detect. handoffs: [] --- # @pharaoh.tailor-fill -Author .pharaoh/project/ tailoring files from a detected-conventions report. +Use when authoring the .pharaoh/project/ tailoring files (id-conventions.yaml, workflows.yaml, artefact-catalog.yaml, checklists/requirement.md) from detected-conventions JSON produced by pharaoh-tailor-detect. See [`skills/pharaoh-tailor-fill/SKILL.md`](../../skills/pharaoh-tailor-fill/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-review.agent.md b/.github/agents/pharaoh.tailor-review.agent.md index 2a2abff..30a5d4e 100644 --- a/.github/agents/pharaoh.tailor-review.agent.md +++ b/.github/agents/pharaoh.tailor-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit .pharaoh/project/ tailoring files against JSON schemas and cross-file consistency. +description: Use when auditing .pharaoh/project/ tailoring files against JSON schemas (id-conventions, workflows, artefact-catalog, checklists frontmatter) plus cross-file consistency checks (every lifecycle state referenced in artefact-catalog exists in workflows.yaml, every prefix in artefact-catalog is declared in id-conventions, etc.). handoffs: [] --- # @pharaoh.tailor-review -Audit .pharaoh/project/ tailoring files against JSON schemas and cross-file consistency. +Use when auditing .pharaoh/project/ tailoring files against JSON schemas (id-conventions, workflows, artefact-catalog, checklists frontmatter) plus cross-file consistency checks (every lifecycle state referenced in artefact-catalog exists in workflows.yaml, every prefix in artefact-catalog is declared in id-conventions, etc.). See [`skills/pharaoh-tailor-review/SKILL.md`](../../skills/pharaoh-tailor-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.toctree-emit.agent.md b/.github/agents/pharaoh.toctree-emit.agent.md index 3aa35f5..1532bdb 100644 --- a/.github/agents/pharaoh.toctree-emit.agent.md +++ b/.github/agents/pharaoh.toctree-emit.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index. +description: Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index.rst` with a Sphinx toctree over them. Prevents orphan-file warnings under `sphinx-build -W`. Does NOT modify the emitted RST files. Does NOT wire the emitted directory into any parent toctree — that is a caller concern. handoffs: [] --- # @pharaoh.toctree-emit -Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index. +Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index.rst` with a Sphinx toctree over them. Prevents orphan-file warnings under `sphinx-build -W`. Does NOT modify the emitted RST files. Does NOT wire the emitted directory into any parent toctree — that is a caller concern. See [`skills/pharaoh-toctree-emit/SKILL.md`](../../skills/pharaoh-toctree-emit/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.trace.agent.md b/.github/agents/pharaoh.trace.agent.md index b6c4ba8..095c023 100644 --- a/.github/agents/pharaoh.trace.agent.md +++ b/.github/agents/pharaoh.trace.agent.md @@ -1,5 +1,5 @@ --- -description: Navigate traceability links between requirements, specifications, implementations, tests, and code in any direction. +description: Use when navigating traceability links between requirements, specifications, implementations, tests, and code in a sphinx-needs project handoffs: - label: Analyze Impact agent: pharaoh.change diff --git a/.github/agents/pharaoh.use-case-diagram-draft.agent.md b/.github/agents/pharaoh.use-case-diagram-draft.agent.md index 59255eb..a32fd11 100644 --- a/.github/agents/pharaoh.use-case-diagram-draft.agent.md +++ b/.github/agents/pharaoh.use-case-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single use-case diagram for one feat — actors, use cases, system boundary. +description: Use when drafting one use-case diagram for a single feat — actors (primary, secondary, external systems), use cases (one per user-facing capability), and system boundary. Renderer-aware (mermaid or plantuml per `.pharaoh/project/diagram-conventions.yaml`). First concrete `*-diagram-draft` skill — others follow the same shape. handoffs: [pharaoh.diagram-review] --- # @pharaoh.use-case-diagram-draft -Draft a single use-case diagram for one feat — actors, use cases, system boundary. +Use when drafting one use-case diagram for a single feat — actors (primary, secondary, external systems), use cases (one per user-facing capability), and system boundary. Renderer-aware (mermaid or plantuml per `.pharaoh/project/diagram-conventions.yaml`). First concrete `*-diagram-draft` skill — others follow the same shape. -See [`skills/pharaoh-use-case-diagram-draft/SKILL.md`](../../skills/pharaoh-use-case-diagram-draft/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-use-case-diagram-draft/SKILL.md`](../../skills/pharaoh-use-case-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.vplan-draft.agent.md b/.github/agents/pharaoh.vplan-draft.agent.md index 2b1b828..037c33c 100644 --- a/.github/agents/pharaoh.vplan-draft.agent.md +++ b/.github/agents/pharaoh.vplan-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single sphinx-needs test-case (verification plan item) for one requirement. +description: Use when drafting a single sphinx-needs test-case (verification plan item) for one requirement. Emits an RST tc__ directive with inputs, steps, and expected outcome, linking to the parent req via :verifies:. handoffs: [] --- # @pharaoh.vplan-draft -Draft a single sphinx-needs test-case (verification plan item) for one requirement. +Use when drafting a single sphinx-needs test-case (verification plan item) for one requirement. Emits an RST tc__ directive with inputs, steps, and expected outcome, linking to the parent req via :verifies:. See [`skills/pharaoh-vplan-draft/SKILL.md`](../../skills/pharaoh-vplan-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.vplan-review.agent.md b/.github/agents/pharaoh.vplan-review.agent.md index af3d327..e01ddbf 100644 --- a/.github/agents/pharaoh.vplan-review.agent.md +++ b/.github/agents/pharaoh.vplan-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single test case against ISO 26262-8 §6 axes plus vplan-specific axes. +description: Use when auditing a single test case against ISO 26262-8 §6 axes plus vplan-specific axes (coverage of parent req, completeness of steps, clarity of expected outcome). Emits structured findings JSON. handoffs: [] --- # @pharaoh.vplan-review -Audit a single test case against ISO 26262-8 §6 axes plus vplan-specific axes. +Use when auditing a single test case against ISO 26262-8 §6 axes plus vplan-specific axes (coverage of parent req, completeness of steps, clarity of expected outcome). Emits structured findings JSON. See [`skills/pharaoh-vplan-review/SKILL.md`](../../skills/pharaoh-vplan-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.write-plan.agent.md b/.github/agents/pharaoh.write-plan.agent.md index 934c18d..a9584a4 100644 --- a/.github/agents/pharaoh.write-plan.agent.md +++ b/.github/agents/pharaoh.write-plan.agent.md @@ -1,10 +1,10 @@ --- -description: Use when you have an intent (e. +description: Use when you have an intent (e.g. "reverse-engineer features and reqs from this module") and need a concrete plan.yaml that pharaoh-execute-plan can run. Picks a plan template by intent, fills project-specific values, emits a plan that validates against schema.md. Does NOT execute anything. handoffs: [] --- # @pharaoh.write-plan -Use when you have an intent (e. +Use when you have an intent (e.g. "reverse-engineer features and reqs from this module") and need a concrete plan.yaml that pharaoh-execute-plan can run. Picks a plan template by intent, fills project-specific values, emits a plan that validates against schema.md. Does NOT execute anything. See [`skills/pharaoh-write-plan/SKILL.md`](../../skills/pharaoh-write-plan/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 5eca926..fd61e50 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -85,6 +85,28 @@ jobs: status=1 fi + # Detect truncation artefacts in description: unbalanced parens, + # brackets, or backticks render as broken Markdown in Copilot UIs + # (see issue #12 — pharaoh.write-plan and pharaoh.toctree-emit). + description=$(echo "$frontmatter" | sed -n 's/^description:[[:space:]]*//p') + opens=$(echo -n "$description" | tr -cd '(' | wc -c) + closes=$(echo -n "$description" | tr -cd ')' | wc -c) + if [ "$opens" -ne "$closes" ]; then + echo "ERROR: $agent_file 'description' has unbalanced parentheses ($opens '(' vs $closes ')')" + status=1 + fi + obrack=$(echo -n "$description" | tr -cd '[' | wc -c) + cbrack=$(echo -n "$description" | tr -cd ']' | wc -c) + if [ "$obrack" -ne "$cbrack" ]; then + echo "ERROR: $agent_file 'description' has unbalanced brackets ($obrack '[' vs $cbrack ']')" + status=1 + fi + ticks=$(echo -n "$description" | tr -cd '`' | wc -c) + if [ $((ticks % 2)) -ne 0 ]; then + echo "ERROR: $agent_file 'description' has unbalanced backticks ($ticks total)" + status=1 + fi + echo "OK: $agent_file" done exit $status