From e6d84d95e5ad536a0bd2487dc912bb36e44bd894 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 28 Apr 2026 13:36:58 +0200 Subject: [PATCH 1/4] docs(readme): rewrite Quick Start, expand Skills tables, fix workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace fictional install commands with real /plugin (Claude Code) and copilot plugin (Copilot CLI) marketplace + install syntax. Both ecosystems can install pharaoh via the existing .claude-plugin/marketplace.json (Copilot also looks there). - Mirror marketplace.json at .github/plugin/marketplace.json so Copilot users find it at the GitHub-native location. Add CI check enforcing the two files stay byte-identical. - Rewrite the Workflow diagram to reflect plan-driven orchestration (pharaoh:write-plan + pharaoh:execute-plan) introduced in PR #9; the previous diagram still showed the deleted composition-skill model. - Expand the Skills section from 24 to 71 entries, regrouped into 8 categories: core workflow, plan-driven orchestration, atomic authoring/review, diagrams, feature reverse-engineering, analysis & audit, tailoring, setup utilities. - Fix three description drifts (pharaoh:spec, pharaoh:flow, pharaoh:process-audit) where README disagreed with each skill's SKILL.md. - Fix dead sphinx-codelinks URL (sphinx-codelinks.useblocks.com → codelinks.useblocks.com). - Drop orphan [pharaoh.decisions] section from pharaoh.toml.example; no skill reads it. Refs #8. --- .github/plugin/marketplace.json | 18 +++ .github/workflows/ci.yaml | 9 ++ README.md | 193 ++++++++++++++++++++++++-------- pharaoh.toml.example | 9 -- 4 files changed, 173 insertions(+), 56 deletions(-) create mode 100644 .github/plugin/marketplace.json diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json new file mode 100644 index 0000000..871dba7 --- /dev/null +++ b/.github/plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "pharaoh-dev", + "description": "Development marketplace for Pharaoh sphinx-needs AI assistant", + "owner": { + "name": "useblocks" + }, + "plugins": [ + { + "name": "pharaoh", + "description": "AI assistant framework for sphinx-needs projects", + "version": "0.1.0", + "source": "./", + "author": { + "name": "useblocks" + } + } + ] +} diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 5eca926..d5f5aea 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -89,6 +89,15 @@ jobs: done exit $status + - name: Marketplace manifests in sync + run: | + if ! diff -q .claude-plugin/marketplace.json .github/plugin/marketplace.json; then + echo "ERROR: .claude-plugin/marketplace.json and .github/plugin/marketplace.json must be identical" + echo "Source of truth: .claude-plugin/marketplace.json" + echo "Run: cp .claude-plugin/marketplace.json .github/plugin/marketplace.json" + exit 1 + fi + - name: Cross-reference skills and agents run: | status=0 diff --git a/README.md b/README.md index 0615134..6e5e46a 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,15 @@ Pharaoh has no runtime binary or Python package. All analysis logic is encoded i ### Claude Code ```bash -# Install the plugin -/plugin install pharaoh +# Add the marketplace, then install the plugin +/plugin marketplace add useblocks/pharaoh +/plugin install pharaoh@pharaoh-dev +# Reload to activate +/reload-plugins +``` + +```bash # Run setup to detect your project and generate pharaoh.toml /pharaoh:setup @@ -22,8 +28,20 @@ Pharaoh has no runtime binary or Python package. All analysis logic is encoded i /pharaoh:mece ``` +To pin to a released version, append a git ref to the marketplace add: + +```bash +/plugin marketplace add useblocks/pharaoh#v1.0.0 +``` + ### GitHub Copilot +```bash +# Add the marketplace, then install the plugin +copilot plugin marketplace add useblocks/pharaoh +copilot plugin install pharaoh@pharaoh-dev +``` + ``` # Run setup to scaffold agents into your project @pharaoh.setup @@ -37,62 +55,143 @@ Pharaoh has no runtime binary or Python package. All analysis logic is encoded i ## Skills / Agents -**Core workflow skills:** - -| Skill (Claude Code) | Purpose | -|---------------------|---------| -| `pharaoh:setup` | Scaffold Pharaoh into a project -- detect structure, generate `pharaoh.toml`, install Copilot agents | -| `pharaoh:change` | Analyze impact of a change -- trace through needs links and codelinks, produce a Change Document | -| `pharaoh:trace` | Navigate traceability in any direction -- show everything linked to a need across all levels | -| `pharaoh:mece` | Gap and redundancy analysis -- find orphans, missing links, MECE violations | -| `pharaoh:release` | Release management -- changelog from requirements, traceability coverage metrics | -| `pharaoh:plan` | Structured implementation planning -- break changes into tasks with workflow enforcement | -| `pharaoh:spec` | Generate spec from requirements -- read needs hierarchy, record decisions, produce spec with plan table | -| `pharaoh:decide` | Record design decisions -- create `decision` needs with alternatives, rationale, and traceability links | +71 atomic skills, organised by purpose. Names below are Claude Code form +(`pharaoh:`); GitHub Copilot form is `pharaoh.`. + +**Core workflow:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:setup` | Set up Pharaoh in a sphinx-needs project -- detect structure, scaffold Copilot agents | +| `pharaoh:change` | Analyse the impact of a requirement change, including traceability to code via codelinks | +| `pharaoh:trace` | Navigate traceability links across requirements, specs, implementations, tests, and code | +| `pharaoh:mece` | Gap and redundancy analysis -- orphans, missing links, MECE violations | +| `pharaoh:plan` | Break requirement changes into structured implementation tasks with workflow enforcement | +| `pharaoh:spec` | Generate a Superpowers-compatible spec and plan document from sphinx-needs requirements | +| `pharaoh:decide` | Record a design decision as a traceable `decision` need with alternatives and rationale | +| `pharaoh:release` | Generate changelog from requirements, summarise requirement changes for version management | + +**Plan-driven orchestration:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:write-plan` | Pick a plan template by intent and emit a `plan.yaml` that validates against schema.md | +| `pharaoh:execute-plan` | Run a `plan.yaml` as a DAG -- dispatch tasks (inline or subagent), thread outputs, validate, persist | +| `pharaoh:audit-fanout` | Run a full project audit in parallel by dispatching 5 atomic audit skills with deduplicated findings | +| `pharaoh:context-gather` | Retrieve rationale memories from a Papyrus workspace before invoking a draft or review skill | +| `pharaoh:finding-record` | Record an audit finding in the shared Papyrus workspace with deterministic deduplication | +| `pharaoh:decision-record` | Record a canonical decision/fact/preference in Papyrus with dedup on (type, canonical_name) | +| `pharaoh:quality-gate` | Final validation step over an aggregated review/MECE/coverage summary -- pass/fail with breaches | +| `pharaoh:gate-advisor` | Read `pharaoh.toml` and report the recommended next gate to switch on, per the phased ladder | +| `pharaoh:dispatch-signal-check` | Verify a plan's declared `execution_mode` matches observed subagent artefacts in `runs/` | +| `pharaoh:reproducibility-check` | Diff two output directories from running the same plan twice to confirm reproducibility | +| `pharaoh:self-review-coverage-check` | Verify every artefact emitted during a plan run received a matching review | +| `pharaoh:output-validate` | Validate a subagent's output against a documented schema (RST/YAML/JSON) before writing to disk | +| `pharaoh:id-allocate` | Pre-allocate globally-unique sphinx-needs IDs before dispatching a fan-out of emission subagents | **Atomic authoring and review chain:** -| Skill (Claude Code) | Purpose | -|---------------------|---------| +| Skill | Purpose | +|-------|---------| | `pharaoh:req-draft` | Draft a single requirement directive with ID, status, and shall-clause body | -| `pharaoh:req-review` | Audit a requirement against ISO 26262-8 §6 axes -- per-axis findings with action items | +| `pharaoh:req-review` | Audit a requirement against the 11 ISO 26262-8 §6 axes -- per-axis findings with action items | | `pharaoh:req-regenerate` | Regenerate a requirement to address findings from req-review | +| `pharaoh:req-from-code` | Read a source file and emit one or more requirement RST directives describing its observable behavior | +| `pharaoh:req-codelink-annotate` | Insert a codelink or backref one-line comment into source code, carrying the trace | +| `pharaoh:req-code-grounding-check` | Verify a drafted requirement against the source file it cites via `:source_doc:` | | `pharaoh:arch-draft` | Draft a single architecture element directive from a parent requirement | -| `pharaoh:arch-review` | Audit an architecture element against ISO 26262-8 §6 axes | +| `pharaoh:arch-review` | Audit an architecture element against ISO 26262-8 §6 axes plus traceability to its requirement | | `pharaoh:vplan-draft` | Draft a test-case directive linking to a parent requirement | | `pharaoh:vplan-review` | Audit a test case against ISO 26262-8 §6 axes plus vplan-specific axes | -| `pharaoh:fmea` | Derive a failure-mode entry (FMEA/DFA row) from a requirement or architecture element | -| `pharaoh:flow` | Orchestrate the full V-model chain (req → arch → vplan → fmea) for one feature context | - -**Analysis and audit skills:** - -| Skill (Claude Code) | Purpose | -|---------------------|---------| -| `pharaoh:coverage-gap` | Detect one gap category (orphan / unverified / duplicate / ...) in a corpus | -| `pharaoh:process-audit` | Full-corpus audit across all gap categories with prioritized findings | -| `pharaoh:lifecycle-check` | Verify artefact lifecycle state and legality of a state transition | -| `pharaoh:standard-conformance` | Evaluate an artefact against a regulatory standard (ISO 26262-8, ASPICE 4.0, ISO/SAE 21434) | - -**Tailoring skills:** - -| Skill (Claude Code) | Purpose | -|---------------------|---------| -| `pharaoh:tailor-detect` | Inspect a project and emit detected conventions for tailoring | -| `pharaoh:tailor-fill` | Author `.pharaoh/project/` tailoring files from detected conventions | -| `pharaoh:tailor-review` | Audit tailoring files against schemas and cross-file consistency | +| `pharaoh:fmea` | Derive a failure-mode entry (FMEA/DFA row) -- cause, effect, severity, occurrence, detection, RPN | +| `pharaoh:fmea-review` | Audit an FMEA entry against the generic FMEA review axes plus per-project addenda | +| `pharaoh:decision-review` | Audit a recorded decision against context/alternatives/consequences and traceability axes | +| `pharaoh:flow` | Orchestrate the full V-model chain (req → arch → vplan → fmea) with a review pass after each step | + +**Diagrams:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:use-case-diagram-draft` | Draft a use-case diagram for a single feat -- actors, use cases, system boundary | +| `pharaoh:component-diagram-draft` | Draft a component-relationship diagram for a bounded scope -- one feature/module/view | +| `pharaoh:sequence-diagram-draft` | Draft a sequence diagram showing ordered interactions between participants | +| `pharaoh:class-diagram-draft` | Draft a class diagram showing types/entities with fields, methods, relationships | +| `pharaoh:state-diagram-draft` | Draft a state-machine diagram showing lifecycle/behavioral states with transitions | +| `pharaoh:activity-diagram-draft` | Draft an activity diagram showing control flow for one procedure or algorithm | +| `pharaoh:block-diagram-draft` | Draft a SysML BDD or IBD showing block structure or part interconnections | +| `pharaoh:deployment-diagram-draft` | Draft a deployment diagram showing physical nodes, deployed artefacts, and channels | +| `pharaoh:fault-tree-diagram-draft` | Draft a fault tree (FTA) decomposing a top hazard event through AND/OR gates | +| `pharaoh:diagram-review` | Audit a diagram block (Mermaid or PlantUML) against trace/parser/required-elements axes | +| `pharaoh:diagram-lint` | Validate Mermaid/PlantUML blocks across a directory by piping each to the renderer parser | + +**Feature reverse-engineering:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:feat-draft-from-docs` | Read existing prose docs and emit feature-level RST directives for documented capabilities | +| `pharaoh:feat-file-map` | Map one feature to the source files that implement it -- `{feat_id: {files, rationale}}` | +| `pharaoh:feat-component-extract` | Walk import edges between a feat's source files and emit a component composition diagram | +| `pharaoh:feat-flow-extract` | Walk the call graph from a feat's entry point and emit a sequence diagram of its control flow | +| `pharaoh:feat-balance` | Check feature granularity -- under/over-decomposition, fused sub-features, redundant pairs | +| `pharaoh:feat-review` | Audit a feature-level need against generic feat axes plus per-project addenda | + +**Analysis and audit:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:coverage-gap` | Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) | +| `pharaoh:process-audit` | Full-corpus audit -- orchestrates `coverage-gap` across all gap categories plus consistency checks | +| `pharaoh:standard-conformance` | Evaluate an artefact against ISO 26262-8 §6, ASPICE 4.0, or ISO/SAE 21434 | +| `pharaoh:lifecycle-check` | Verify an artefact's lifecycle state and legality of a state transition | +| `pharaoh:status-lifecycle-check` | Release-gate check -- confirm zero needs remain in `draft` status across the corpus | +| `pharaoh:link-completeness-check` | Verify outgoing-link coverage across a needs.json graph for every declared link type | +| `pharaoh:id-convention-check` | Verify every need id matches the regex declared for its type in `id-conventions.yaml` | +| `pharaoh:review-completeness` | Flag needs missing required `:reviewer:` or `:approved_by:` fields per the artefact catalog | +| `pharaoh:api-coverage-check` | Verify a source file is covered by the need catalogue (CREQ source_doc + exception class names) | +| `pharaoh:papyrus-non-empty-check` | Verify a Papyrus workspace received writes during a plan run -- counts directives across `.papyrus/memory/` | + +**Tailoring:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:tailor-detect` | Inspect a project and emit a structured report of detected conventions | +| `pharaoh:tailor-fill` | Author `.pharaoh/project/` tailoring files from detected-conventions JSON | +| `pharaoh:tailor-bootstrap` | Generate minimal tailoring files from declared types post-bootstrap, pre any needs authoring | +| `pharaoh:tailor-code-grounding-filters` | Author a project's `code-grounding-filters.yaml` from observed stack conventions | +| `pharaoh:tailor-review` | Audit tailoring files against schemas plus cross-file consistency | + +**Setup utilities:** + +| Skill | Purpose | +|-------|---------| +| `pharaoh:bootstrap` | Add sphinx-needs extension and declare need types so `sphinx-build` produces a valid needs.json | +| `pharaoh:sphinx-extension-add` | Idempotently add sphinx extensions to `conf.py` and install corresponding pypi packages | +| `pharaoh:toctree-emit` | Emit or regenerate an `index.rst` toctree over a set of generated RST files, preventing orphan warnings | +| `pharaoh:prose-migrate` | Sentence-by-sentence migration proposal when generated feat RST would collide with prose docs | ## Workflow +Authoring orchestration is plan-driven: `pharaoh:write-plan` emits a `plan.yaml`, +`pharaoh:execute-plan` runs it as a DAG dispatching atomic skills. + ``` -pharaoh:spec -> pharaoh:decide (for gaps) - -> produces spec doc with plan table - | -pharaoh:plan -> pharaoh:change -> pharaoh:req-draft -> pharaoh:req-review -> pharaoh:release - -> pharaoh:arch-draft -> pharaoh:arch-review - -> pharaoh:vplan-draft -> pharaoh:vplan-review - -> pharaoh:fmea - -> pharaoh:mece (optional, for gap analysis) - -> pharaoh:trace (optional, for exploration) +pharaoh:spec -> pharaoh:decide (for gaps) + -> produces spec doc with plan table + +pharaoh:write-plan -> emits .pharaoh/plans/.yaml + -> pharaoh:execute-plan + |-- pharaoh:req-draft -> pharaoh:req-review + |-- pharaoh:arch-draft -> pharaoh:arch-review + |-- pharaoh:vplan-draft -> pharaoh:vplan-review + |-- pharaoh:fmea -> pharaoh:fmea-review + |-- pharaoh:*-diagram-draft -> pharaoh:diagram-review + |-- pharaoh:quality-gate (terminal) + +pharaoh:flow -> shortcut for the V-model chain on one feature context +pharaoh:change -> impact analysis, feeds plan inputs +pharaoh:mece -> gap analysis (standalone or as a plan task) +pharaoh:trace -> traceability exploration +pharaoh:release -> reads completed artefacts, emits changelog ``` ## Experience Tiers @@ -152,7 +251,7 @@ Pharaoh never re-defines these settings. `pharaoh.toml` only controls Pharaoh's ## sphinx-codelinks Support -When a project uses [sphinx-codelinks](https://sphinx-codelinks.useblocks.com/), Pharaoh follows codelink references in change analysis and traceability. A change to a requirement surfaces affected code files, not just other requirements. +When a project uses [sphinx-codelinks](https://codelinks.useblocks.com/), Pharaoh follows codelink references in change analysis and traceability. A change to a requirement surfaces affected code files, not just other requirements. ## License diff --git a/pharaoh.toml.example b/pharaoh.toml.example index 9bb8a21..aec78dd 100644 --- a/pharaoh.toml.example +++ b/pharaoh.toml.example @@ -36,12 +36,3 @@ required_links = [ [pharaoh.codelinks] # Follow sphinx-codelinks in change analysis enabled = true - -[pharaoh.decisions] -# Default file for new decision needs (relative to docs source root) -# If absent, decisions go to decisions.rst in same directory as affected requirement -default_file = "decisions.rst" -# Default status for decisions created standalone -default_status = "proposed" -# Default status for decisions created during pharaoh:spec -spec_status = "accepted" From 6f1fdb03e2dceb6eaffef0ced929dd878c45d4ad Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 28 Apr 2026 13:50:02 +0200 Subject: [PATCH 2/4] docs(readme): fix Claude Code slash form (doubled pharaoh- prefix) Pharaoh's skill names already include the `pharaoh-` prefix (e.g. SKILL.md frontmatter `name: pharaoh-setup`), so the Claude Code slash namespace lands on `/pharaoh:pharaoh-setup`, not `/pharaoh:setup`. Verified against the installed plugin: chrome-devtools-mcp's skills are named cleanly (`troubleshooting` -> `/chrome-devtools-mcp:troubleshooting`), while pharaoh and papyrus self-prefix (`pharaoh-setup` -> `/pharaoh:pharaoh-setup`). The Copilot side already strips the prefix in agent file names (`.github/agents/pharaoh.setup.agent.md` -> `@pharaoh.setup`), so the two ecosystems address skills asymmetrically. README now documents the asymmetry up front and uses the Claude Code form throughout the tables and Quick Start. --- README.md | 190 +++++++++++++++++++++++++++--------------------------- 1 file changed, 96 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 6e5e46a..4d1222f 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,13 @@ Pharaoh has no runtime binary or Python package. All analysis logic is encoded i ```bash # Run setup to detect your project and generate pharaoh.toml -/pharaoh:setup +/pharaoh:pharaoh-setup # Analyze the impact of a change -/pharaoh:change REQ_001 +/pharaoh:pharaoh-change REQ_001 # Check for traceability gaps -/pharaoh:mece +/pharaoh:pharaoh-mece ``` To pin to a released version, append a git ref to the marketplace add: @@ -55,143 +55,145 @@ copilot plugin install pharaoh@pharaoh-dev ## Skills / Agents -71 atomic skills, organised by purpose. Names below are Claude Code form -(`pharaoh:`); GitHub Copilot form is `pharaoh.`. +71 atomic skills, organised by purpose. Names below are the Claude Code +slash form `pharaoh:pharaoh-` (the `pharaoh-` prefix is part of each +skill's own name). The GitHub Copilot equivalent strips the redundant +prefix: `@pharaoh.`. **Core workflow:** | Skill | Purpose | |-------|---------| -| `pharaoh:setup` | Set up Pharaoh in a sphinx-needs project -- detect structure, scaffold Copilot agents | -| `pharaoh:change` | Analyse the impact of a requirement change, including traceability to code via codelinks | -| `pharaoh:trace` | Navigate traceability links across requirements, specs, implementations, tests, and code | -| `pharaoh:mece` | Gap and redundancy analysis -- orphans, missing links, MECE violations | -| `pharaoh:plan` | Break requirement changes into structured implementation tasks with workflow enforcement | -| `pharaoh:spec` | Generate a Superpowers-compatible spec and plan document from sphinx-needs requirements | -| `pharaoh:decide` | Record a design decision as a traceable `decision` need with alternatives and rationale | -| `pharaoh:release` | Generate changelog from requirements, summarise requirement changes for version management | +| `pharaoh:pharaoh-setup` | Set up Pharaoh in a sphinx-needs project -- detect structure, scaffold Copilot agents | +| `pharaoh:pharaoh-change` | Analyse the impact of a requirement change, including traceability to code via codelinks | +| `pharaoh:pharaoh-trace` | Navigate traceability links across requirements, specs, implementations, tests, and code | +| `pharaoh:pharaoh-mece` | Gap and redundancy analysis -- orphans, missing links, MECE violations | +| `pharaoh:pharaoh-plan` | Break requirement changes into structured implementation tasks with workflow enforcement | +| `pharaoh:pharaoh-spec` | Generate a Superpowers-compatible spec and plan document from sphinx-needs requirements | +| `pharaoh:pharaoh-decide` | Record a design decision as a traceable `decision` need with alternatives and rationale | +| `pharaoh:pharaoh-release` | Generate changelog from requirements, summarise requirement changes for version management | **Plan-driven orchestration:** | Skill | Purpose | |-------|---------| -| `pharaoh:write-plan` | Pick a plan template by intent and emit a `plan.yaml` that validates against schema.md | -| `pharaoh:execute-plan` | Run a `plan.yaml` as a DAG -- dispatch tasks (inline or subagent), thread outputs, validate, persist | -| `pharaoh:audit-fanout` | Run a full project audit in parallel by dispatching 5 atomic audit skills with deduplicated findings | -| `pharaoh:context-gather` | Retrieve rationale memories from a Papyrus workspace before invoking a draft or review skill | -| `pharaoh:finding-record` | Record an audit finding in the shared Papyrus workspace with deterministic deduplication | -| `pharaoh:decision-record` | Record a canonical decision/fact/preference in Papyrus with dedup on (type, canonical_name) | -| `pharaoh:quality-gate` | Final validation step over an aggregated review/MECE/coverage summary -- pass/fail with breaches | -| `pharaoh:gate-advisor` | Read `pharaoh.toml` and report the recommended next gate to switch on, per the phased ladder | -| `pharaoh:dispatch-signal-check` | Verify a plan's declared `execution_mode` matches observed subagent artefacts in `runs/` | -| `pharaoh:reproducibility-check` | Diff two output directories from running the same plan twice to confirm reproducibility | -| `pharaoh:self-review-coverage-check` | Verify every artefact emitted during a plan run received a matching review | -| `pharaoh:output-validate` | Validate a subagent's output against a documented schema (RST/YAML/JSON) before writing to disk | -| `pharaoh:id-allocate` | Pre-allocate globally-unique sphinx-needs IDs before dispatching a fan-out of emission subagents | +| `pharaoh:pharaoh-write-plan` | Pick a plan template by intent and emit a `plan.yaml` that validates against schema.md | +| `pharaoh:pharaoh-execute-plan` | Run a `plan.yaml` as a DAG -- dispatch tasks (inline or subagent), thread outputs, validate, persist | +| `pharaoh:pharaoh-audit-fanout` | Run a full project audit in parallel by dispatching 5 atomic audit skills with deduplicated findings | +| `pharaoh:pharaoh-context-gather` | Retrieve rationale memories from a Papyrus workspace before invoking a draft or review skill | +| `pharaoh:pharaoh-finding-record` | Record an audit finding in the shared Papyrus workspace with deterministic deduplication | +| `pharaoh:pharaoh-decision-record` | Record a canonical decision/fact/preference in Papyrus with dedup on (type, canonical_name) | +| `pharaoh:pharaoh-quality-gate` | Final validation step over an aggregated review/MECE/coverage summary -- pass/fail with breaches | +| `pharaoh:pharaoh-gate-advisor` | Read `pharaoh.toml` and report the recommended next gate to switch on, per the phased ladder | +| `pharaoh:pharaoh-dispatch-signal-check` | Verify a plan's declared `execution_mode` matches observed subagent artefacts in `runs/` | +| `pharaoh:pharaoh-reproducibility-check` | Diff two output directories from running the same plan twice to confirm reproducibility | +| `pharaoh:pharaoh-self-review-coverage-check` | Verify every artefact emitted during a plan run received a matching review | +| `pharaoh:pharaoh-output-validate` | Validate a subagent's output against a documented schema (RST/YAML/JSON) before writing to disk | +| `pharaoh:pharaoh-id-allocate` | Pre-allocate globally-unique sphinx-needs IDs before dispatching a fan-out of emission subagents | **Atomic authoring and review chain:** | Skill | Purpose | |-------|---------| -| `pharaoh:req-draft` | Draft a single requirement directive with ID, status, and shall-clause body | -| `pharaoh:req-review` | Audit a requirement against the 11 ISO 26262-8 §6 axes -- per-axis findings with action items | -| `pharaoh:req-regenerate` | Regenerate a requirement to address findings from req-review | -| `pharaoh:req-from-code` | Read a source file and emit one or more requirement RST directives describing its observable behavior | -| `pharaoh:req-codelink-annotate` | Insert a codelink or backref one-line comment into source code, carrying the trace | -| `pharaoh:req-code-grounding-check` | Verify a drafted requirement against the source file it cites via `:source_doc:` | -| `pharaoh:arch-draft` | Draft a single architecture element directive from a parent requirement | -| `pharaoh:arch-review` | Audit an architecture element against ISO 26262-8 §6 axes plus traceability to its requirement | -| `pharaoh:vplan-draft` | Draft a test-case directive linking to a parent requirement | -| `pharaoh:vplan-review` | Audit a test case against ISO 26262-8 §6 axes plus vplan-specific axes | -| `pharaoh:fmea` | Derive a failure-mode entry (FMEA/DFA row) -- cause, effect, severity, occurrence, detection, RPN | -| `pharaoh:fmea-review` | Audit an FMEA entry against the generic FMEA review axes plus per-project addenda | -| `pharaoh:decision-review` | Audit a recorded decision against context/alternatives/consequences and traceability axes | -| `pharaoh:flow` | Orchestrate the full V-model chain (req → arch → vplan → fmea) with a review pass after each step | +| `pharaoh:pharaoh-req-draft` | Draft a single requirement directive with ID, status, and shall-clause body | +| `pharaoh:pharaoh-req-review` | Audit a requirement against the 11 ISO 26262-8 §6 axes -- per-axis findings with action items | +| `pharaoh:pharaoh-req-regenerate` | Regenerate a requirement to address findings from req-review | +| `pharaoh:pharaoh-req-from-code` | Read a source file and emit one or more requirement RST directives describing its observable behavior | +| `pharaoh:pharaoh-req-codelink-annotate` | Insert a codelink or backref one-line comment into source code, carrying the trace | +| `pharaoh:pharaoh-req-code-grounding-check` | Verify a drafted requirement against the source file it cites via `:source_doc:` | +| `pharaoh:pharaoh-arch-draft` | Draft a single architecture element directive from a parent requirement | +| `pharaoh:pharaoh-arch-review` | Audit an architecture element against ISO 26262-8 §6 axes plus traceability to its requirement | +| `pharaoh:pharaoh-vplan-draft` | Draft a test-case directive linking to a parent requirement | +| `pharaoh:pharaoh-vplan-review` | Audit a test case against ISO 26262-8 §6 axes plus vplan-specific axes | +| `pharaoh:pharaoh-fmea` | Derive a failure-mode entry (FMEA/DFA row) -- cause, effect, severity, occurrence, detection, RPN | +| `pharaoh:pharaoh-fmea-review` | Audit an FMEA entry against the generic FMEA review axes plus per-project addenda | +| `pharaoh:pharaoh-decision-review` | Audit a recorded decision against context/alternatives/consequences and traceability axes | +| `pharaoh:pharaoh-flow` | Orchestrate the full V-model chain (req → arch → vplan → fmea) with a review pass after each step | **Diagrams:** | Skill | Purpose | |-------|---------| -| `pharaoh:use-case-diagram-draft` | Draft a use-case diagram for a single feat -- actors, use cases, system boundary | -| `pharaoh:component-diagram-draft` | Draft a component-relationship diagram for a bounded scope -- one feature/module/view | -| `pharaoh:sequence-diagram-draft` | Draft a sequence diagram showing ordered interactions between participants | -| `pharaoh:class-diagram-draft` | Draft a class diagram showing types/entities with fields, methods, relationships | -| `pharaoh:state-diagram-draft` | Draft a state-machine diagram showing lifecycle/behavioral states with transitions | -| `pharaoh:activity-diagram-draft` | Draft an activity diagram showing control flow for one procedure or algorithm | -| `pharaoh:block-diagram-draft` | Draft a SysML BDD or IBD showing block structure or part interconnections | -| `pharaoh:deployment-diagram-draft` | Draft a deployment diagram showing physical nodes, deployed artefacts, and channels | -| `pharaoh:fault-tree-diagram-draft` | Draft a fault tree (FTA) decomposing a top hazard event through AND/OR gates | -| `pharaoh:diagram-review` | Audit a diagram block (Mermaid or PlantUML) against trace/parser/required-elements axes | -| `pharaoh:diagram-lint` | Validate Mermaid/PlantUML blocks across a directory by piping each to the renderer parser | +| `pharaoh:pharaoh-use-case-diagram-draft` | Draft a use-case diagram for a single feat -- actors, use cases, system boundary | +| `pharaoh:pharaoh-component-diagram-draft` | Draft a component-relationship diagram for a bounded scope -- one feature/module/view | +| `pharaoh:pharaoh-sequence-diagram-draft` | Draft a sequence diagram showing ordered interactions between participants | +| `pharaoh:pharaoh-class-diagram-draft` | Draft a class diagram showing types/entities with fields, methods, relationships | +| `pharaoh:pharaoh-state-diagram-draft` | Draft a state-machine diagram showing lifecycle/behavioral states with transitions | +| `pharaoh:pharaoh-activity-diagram-draft` | Draft an activity diagram showing control flow for one procedure or algorithm | +| `pharaoh:pharaoh-block-diagram-draft` | Draft a SysML BDD or IBD showing block structure or part interconnections | +| `pharaoh:pharaoh-deployment-diagram-draft` | Draft a deployment diagram showing physical nodes, deployed artefacts, and channels | +| `pharaoh:pharaoh-fault-tree-diagram-draft` | Draft a fault tree (FTA) decomposing a top hazard event through AND/OR gates | +| `pharaoh:pharaoh-diagram-review` | Audit a diagram block (Mermaid or PlantUML) against trace/parser/required-elements axes | +| `pharaoh:pharaoh-diagram-lint` | Validate Mermaid/PlantUML blocks across a directory by piping each to the renderer parser | **Feature reverse-engineering:** | Skill | Purpose | |-------|---------| -| `pharaoh:feat-draft-from-docs` | Read existing prose docs and emit feature-level RST directives for documented capabilities | -| `pharaoh:feat-file-map` | Map one feature to the source files that implement it -- `{feat_id: {files, rationale}}` | -| `pharaoh:feat-component-extract` | Walk import edges between a feat's source files and emit a component composition diagram | -| `pharaoh:feat-flow-extract` | Walk the call graph from a feat's entry point and emit a sequence diagram of its control flow | -| `pharaoh:feat-balance` | Check feature granularity -- under/over-decomposition, fused sub-features, redundant pairs | -| `pharaoh:feat-review` | Audit a feature-level need against generic feat axes plus per-project addenda | +| `pharaoh:pharaoh-feat-draft-from-docs` | Read existing prose docs and emit feature-level RST directives for documented capabilities | +| `pharaoh:pharaoh-feat-file-map` | Map one feature to the source files that implement it -- `{feat_id: {files, rationale}}` | +| `pharaoh:pharaoh-feat-component-extract` | Walk import edges between a feat's source files and emit a component composition diagram | +| `pharaoh:pharaoh-feat-flow-extract` | Walk the call graph from a feat's entry point and emit a sequence diagram of its control flow | +| `pharaoh:pharaoh-feat-balance` | Check feature granularity -- under/over-decomposition, fused sub-features, redundant pairs | +| `pharaoh:pharaoh-feat-review` | Audit a feature-level need against generic feat axes plus per-project addenda | **Analysis and audit:** | Skill | Purpose | |-------|---------| -| `pharaoh:coverage-gap` | Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) | -| `pharaoh:process-audit` | Full-corpus audit -- orchestrates `coverage-gap` across all gap categories plus consistency checks | -| `pharaoh:standard-conformance` | Evaluate an artefact against ISO 26262-8 §6, ASPICE 4.0, or ISO/SAE 21434 | -| `pharaoh:lifecycle-check` | Verify an artefact's lifecycle state and legality of a state transition | -| `pharaoh:status-lifecycle-check` | Release-gate check -- confirm zero needs remain in `draft` status across the corpus | -| `pharaoh:link-completeness-check` | Verify outgoing-link coverage across a needs.json graph for every declared link type | -| `pharaoh:id-convention-check` | Verify every need id matches the regex declared for its type in `id-conventions.yaml` | -| `pharaoh:review-completeness` | Flag needs missing required `:reviewer:` or `:approved_by:` fields per the artefact catalog | -| `pharaoh:api-coverage-check` | Verify a source file is covered by the need catalogue (CREQ source_doc + exception class names) | -| `pharaoh:papyrus-non-empty-check` | Verify a Papyrus workspace received writes during a plan run -- counts directives across `.papyrus/memory/` | +| `pharaoh:pharaoh-coverage-gap` | Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) | +| `pharaoh:pharaoh-process-audit` | Full-corpus audit -- orchestrates `coverage-gap` across all gap categories plus consistency checks | +| `pharaoh:pharaoh-standard-conformance` | Evaluate an artefact against ISO 26262-8 §6, ASPICE 4.0, or ISO/SAE 21434 | +| `pharaoh:pharaoh-lifecycle-check` | Verify an artefact's lifecycle state and legality of a state transition | +| `pharaoh:pharaoh-status-lifecycle-check` | Release-gate check -- confirm zero needs remain in `draft` status across the corpus | +| `pharaoh:pharaoh-link-completeness-check` | Verify outgoing-link coverage across a needs.json graph for every declared link type | +| `pharaoh:pharaoh-id-convention-check` | Verify every need id matches the regex declared for its type in `id-conventions.yaml` | +| `pharaoh:pharaoh-review-completeness` | Flag needs missing required `:reviewer:` or `:approved_by:` fields per the artefact catalog | +| `pharaoh:pharaoh-api-coverage-check` | Verify a source file is covered by the need catalogue (CREQ source_doc + exception class names) | +| `pharaoh:pharaoh-papyrus-non-empty-check` | Verify a Papyrus workspace received writes during a plan run -- counts directives across `.papyrus/memory/` | **Tailoring:** | Skill | Purpose | |-------|---------| -| `pharaoh:tailor-detect` | Inspect a project and emit a structured report of detected conventions | -| `pharaoh:tailor-fill` | Author `.pharaoh/project/` tailoring files from detected-conventions JSON | -| `pharaoh:tailor-bootstrap` | Generate minimal tailoring files from declared types post-bootstrap, pre any needs authoring | -| `pharaoh:tailor-code-grounding-filters` | Author a project's `code-grounding-filters.yaml` from observed stack conventions | -| `pharaoh:tailor-review` | Audit tailoring files against schemas plus cross-file consistency | +| `pharaoh:pharaoh-tailor-detect` | Inspect a project and emit a structured report of detected conventions | +| `pharaoh:pharaoh-tailor-fill` | Author `.pharaoh/project/` tailoring files from detected-conventions JSON | +| `pharaoh:pharaoh-tailor-bootstrap` | Generate minimal tailoring files from declared types post-bootstrap, pre any needs authoring | +| `pharaoh:pharaoh-tailor-code-grounding-filters` | Author a project's `code-grounding-filters.yaml` from observed stack conventions | +| `pharaoh:pharaoh-tailor-review` | Audit tailoring files against schemas plus cross-file consistency | **Setup utilities:** | Skill | Purpose | |-------|---------| -| `pharaoh:bootstrap` | Add sphinx-needs extension and declare need types so `sphinx-build` produces a valid needs.json | -| `pharaoh:sphinx-extension-add` | Idempotently add sphinx extensions to `conf.py` and install corresponding pypi packages | -| `pharaoh:toctree-emit` | Emit or regenerate an `index.rst` toctree over a set of generated RST files, preventing orphan warnings | -| `pharaoh:prose-migrate` | Sentence-by-sentence migration proposal when generated feat RST would collide with prose docs | +| `pharaoh:pharaoh-bootstrap` | Add sphinx-needs extension and declare need types so `sphinx-build` produces a valid needs.json | +| `pharaoh:pharaoh-sphinx-extension-add` | Idempotently add sphinx extensions to `conf.py` and install corresponding pypi packages | +| `pharaoh:pharaoh-toctree-emit` | Emit or regenerate an `index.rst` toctree over a set of generated RST files, preventing orphan warnings | +| `pharaoh:pharaoh-prose-migrate` | Sentence-by-sentence migration proposal when generated feat RST would collide with prose docs | ## Workflow -Authoring orchestration is plan-driven: `pharaoh:write-plan` emits a `plan.yaml`, -`pharaoh:execute-plan` runs it as a DAG dispatching atomic skills. +Authoring orchestration is plan-driven: `pharaoh:pharaoh-write-plan` emits a `plan.yaml`, +`pharaoh:pharaoh-execute-plan` runs it as a DAG dispatching atomic skills. ``` -pharaoh:spec -> pharaoh:decide (for gaps) +pharaoh:pharaoh-spec -> pharaoh:pharaoh-decide (for gaps) -> produces spec doc with plan table -pharaoh:write-plan -> emits .pharaoh/plans/.yaml - -> pharaoh:execute-plan - |-- pharaoh:req-draft -> pharaoh:req-review - |-- pharaoh:arch-draft -> pharaoh:arch-review - |-- pharaoh:vplan-draft -> pharaoh:vplan-review - |-- pharaoh:fmea -> pharaoh:fmea-review - |-- pharaoh:*-diagram-draft -> pharaoh:diagram-review - |-- pharaoh:quality-gate (terminal) - -pharaoh:flow -> shortcut for the V-model chain on one feature context -pharaoh:change -> impact analysis, feeds plan inputs -pharaoh:mece -> gap analysis (standalone or as a plan task) -pharaoh:trace -> traceability exploration -pharaoh:release -> reads completed artefacts, emits changelog +pharaoh:pharaoh-write-plan -> emits .pharaoh/plans/.yaml + -> pharaoh:pharaoh-execute-plan + |-- pharaoh:pharaoh-req-draft -> pharaoh:pharaoh-req-review + |-- pharaoh:pharaoh-arch-draft -> pharaoh:pharaoh-arch-review + |-- pharaoh:pharaoh-vplan-draft -> pharaoh:pharaoh-vplan-review + |-- pharaoh:pharaoh-fmea -> pharaoh:pharaoh-fmea-review + |-- pharaoh:pharaoh-*-diagram-draft -> pharaoh:pharaoh-diagram-review + |-- pharaoh:pharaoh-quality-gate (terminal) + +pharaoh:pharaoh-flow -> shortcut for the V-model chain on one feature context +pharaoh:pharaoh-change -> impact analysis, feeds plan inputs +pharaoh:pharaoh-mece -> gap analysis (standalone or as a plan task) +pharaoh:pharaoh-trace -> traceability exploration +pharaoh:pharaoh-release -> reads completed artefacts, emits changelog ``` ## Experience Tiers @@ -239,7 +241,7 @@ See [`pharaoh.toml.example`](pharaoh.toml.example) for a fully commented templat ### Advisory vs Enforcing Mode - **Advisory** (default): Skills suggest the recommended workflow but never block. Tips are shown for skipped steps. -- **Enforcing**: Skills check prerequisites and block if not met. For example, authoring skills (e.g. `pharaoh:req-draft`) require `pharaoh:change` to be run and acknowledged first. +- **Enforcing**: Skills check prerequisites and block if not met. For example, authoring skills (e.g. `pharaoh:pharaoh-req-draft`) require `pharaoh:pharaoh-change` to be run and acknowledged first. ### Project Configuration From 2554ea460e2beb9761090fc754859f8aada33161 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 28 Apr 2026 13:56:11 +0200 Subject: [PATCH 3/4] build: symlink .claude-plugin/marketplace.json to .github/plugin/ Adopt the layout used by github/copilot-plugins (the official Copilot default marketplace): .github/plugin/marketplace.json is the source of truth, .claude-plugin/marketplace.json is a symlink (git mode 120000) to ../.github/plugin/marketplace.json. This keeps a single source of truth -- both Claude Code (which checks .claude-plugin/) and Copilot CLI (which prefers .github/plugin/) find the same file with no drift possible. Drops the CI diff check that was guarding against the previous duplicate-file approach. --- .claude-plugin/marketplace.json | 19 +------------------ .github/workflows/ci.yaml | 9 --------- 2 files changed, 1 insertion(+), 27 deletions(-) mode change 100644 => 120000 .claude-plugin/marketplace.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index 871dba7..0000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "name": "pharaoh-dev", - "description": "Development marketplace for Pharaoh sphinx-needs AI assistant", - "owner": { - "name": "useblocks" - }, - "plugins": [ - { - "name": "pharaoh", - "description": "AI assistant framework for sphinx-needs projects", - "version": "0.1.0", - "source": "./", - "author": { - "name": "useblocks" - } - } - ] -} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 120000 index 0000000..599da46 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1 @@ +../.github/plugin/marketplace.json \ No newline at end of file diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index d5f5aea..5eca926 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -89,15 +89,6 @@ jobs: done exit $status - - name: Marketplace manifests in sync - run: | - if ! diff -q .claude-plugin/marketplace.json .github/plugin/marketplace.json; then - echo "ERROR: .claude-plugin/marketplace.json and .github/plugin/marketplace.json must be identical" - echo "Source of truth: .claude-plugin/marketplace.json" - echo "Run: cp .claude-plugin/marketplace.json .github/plugin/marketplace.json" - exit 1 - fi - - name: Cross-reference skills and agents run: | status=0 From 2af2e3a9e29c39fa7ed62210c5901c97258ad470 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 28 Apr 2026 15:31:34 +0200 Subject: [PATCH 4/4] docs(readme): address Copilot review comments - s/Analyse/Analyze/ in pharaoh:change row to match Quick Start's variant ("Analyze the impact of a change") used elsewhere in the doc. - Workflow section now correctly describes pharaoh:pharaoh-write-plan as a pure transformation that returns plan.yaml content as text. The previous wording said it "emits .pharaoh/plans/.yaml", which contradicts the skill's SKILL.md ("Pure transformation: intent + project state -> plan text. Does not write artefacts. Does not mutate .pharaoh/."). The caller saves the YAML and hands the path to pharaoh:pharaoh-execute-plan. --- README.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 4d1222f..75fd6b4 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ prefix: `@pharaoh.`. | Skill | Purpose | |-------|---------| | `pharaoh:pharaoh-setup` | Set up Pharaoh in a sphinx-needs project -- detect structure, scaffold Copilot agents | -| `pharaoh:pharaoh-change` | Analyse the impact of a requirement change, including traceability to code via codelinks | +| `pharaoh:pharaoh-change` | Analyze the impact of a requirement change, including traceability to code via codelinks | | `pharaoh:pharaoh-trace` | Navigate traceability links across requirements, specs, implementations, tests, and code | | `pharaoh:pharaoh-mece` | Gap and redundancy analysis -- orphans, missing links, MECE violations | | `pharaoh:pharaoh-plan` | Break requirement changes into structured implementation tasks with workflow enforcement | @@ -173,21 +173,24 @@ prefix: `@pharaoh.`. ## Workflow -Authoring orchestration is plan-driven: `pharaoh:pharaoh-write-plan` emits a `plan.yaml`, -`pharaoh:pharaoh-execute-plan` runs it as a DAG dispatching atomic skills. +Authoring orchestration is plan-driven. `pharaoh:pharaoh-write-plan` is a +pure transformation -- it returns plan.yaml content as text without +touching the filesystem. The caller saves it (anywhere) and hands the +path to `pharaoh:pharaoh-execute-plan`, which runs the DAG dispatching +atomic skills. ``` pharaoh:pharaoh-spec -> pharaoh:pharaoh-decide (for gaps) - -> produces spec doc with plan table - -pharaoh:pharaoh-write-plan -> emits .pharaoh/plans/.yaml - -> pharaoh:pharaoh-execute-plan - |-- pharaoh:pharaoh-req-draft -> pharaoh:pharaoh-req-review - |-- pharaoh:pharaoh-arch-draft -> pharaoh:pharaoh-arch-review - |-- pharaoh:pharaoh-vplan-draft -> pharaoh:pharaoh-vplan-review - |-- pharaoh:pharaoh-fmea -> pharaoh:pharaoh-fmea-review - |-- pharaoh:pharaoh-*-diagram-draft -> pharaoh:pharaoh-diagram-review - |-- pharaoh:pharaoh-quality-gate (terminal) + -> produces spec doc with plan table + +pharaoh:pharaoh-write-plan -> returns plan.yaml text (caller saves to a path) + -> pharaoh:pharaoh-execute-plan + |-- pharaoh:pharaoh-req-draft -> pharaoh:pharaoh-req-review + |-- pharaoh:pharaoh-arch-draft -> pharaoh:pharaoh-arch-review + |-- pharaoh:pharaoh-vplan-draft -> pharaoh:pharaoh-vplan-review + |-- pharaoh:pharaoh-fmea -> pharaoh:pharaoh-fmea-review + |-- pharaoh:pharaoh-*-diagram-draft -> pharaoh:pharaoh-diagram-review + |-- pharaoh:pharaoh-quality-gate (terminal) pharaoh:pharaoh-flow -> shortcut for the V-model chain on one feature context pharaoh:pharaoh-change -> impact analysis, feeds plan inputs