docs(readme): rewrite Quick Start, expand Skills tables, fix workflow

.claude-plugin/marketplace.json

@@ -0,0 +1 @@
+../.github/plugin/marketplace.json

.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"
+      }
+    }
+  ]
+}

README.md

@@ -9,21 +9,39 @@ 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
+/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:
+
+```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,148 @@ 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 the Claude Code
+slash form `pharaoh:pharaoh-<name>` (the `pharaoh-` prefix is part of each
+skill's own name). The GitHub Copilot equivalent strips the redundant
+prefix: `@pharaoh.<name>`.
+
+**Core workflow:**
+
+| Skill | Purpose |
+|-------|---------|
+| `pharaoh:pharaoh-setup` | Set up Pharaoh in a sphinx-needs project -- detect structure, scaffold Copilot agents |
+| `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 |
+| `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: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 (Claude Code) | 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-regenerate` | Regenerate a requirement to address findings from req-review |
-| `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: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 |
+| Skill | Purpose |
+|-------|---------|
+| `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: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: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: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: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: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: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: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:pharaoh-spec       -> pharaoh:pharaoh-decide (for gaps)
+                              -> produces spec doc with plan table
+
+pharaoh:pharaoh-write-plan -> returns plan.yaml text (caller saves to a path)
+                              -> pharaoh:pharaoh-execute-plan <plan_path>
+                                    |-- 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
@@ -140,7 +244,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
 
@@ -152,7 +256,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
 

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"