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