Atomic-skill refactor + Papyrus memory integration#7
Merged
Conversation
Atomic refactor of authoring workflow into single-artefact primitives:
* pharaoh-req-draft / pharaoh-req-review / pharaoh-req-regenerate
ISO 26262 Part 6 §7 single-requirement authoring + per-axis
review + targeted regeneration from review findings.
* pharaoh-arch-draft / pharaoh-arch-review
Single architecture element from a parent requirement, with
per-axis audit.
* pharaoh-vplan-draft / pharaoh-vplan-review
Single test-case from a parent requirement, with per-axis audit.
* pharaoh-fmea
Single failure-mode entry scored on severity/occurrence/detection.
Each primitive is indivisible, has a strict input/output contract,
execution-based reward where possible, reusable across flows, and
non-interfering.
Companion: hand-authored Score tailoring pilot
(examples/score/.pharaoh/project/{artefact-catalog,id-conventions,
workflows,checklists}) exercises the primitives against a realistic
safety-critical project layout.
Project-tailoring layer: per-project content lives under .pharaoh/project/ (not in domain skills, which stay generic). * pharaoh-tailor-detect — inspect project, report detected conventions * pharaoh-tailor-fill — author .pharaoh/project/ from detected conventions * pharaoh-tailor-review — schema + cross-file consistency audit Companion JSON schemas in examples/score/.pharaoh/project/schemas/ (artefact-catalog, checklists-frontmatter, id-conventions, workflows) anchor deterministic validation for tailor-review.
Cross-cutting gap and conformance auditors over an existing corpus: * pharaoh-lifecycle-check — verify state transitions against workflows.yaml * pharaoh-standard-conformance — per-indicator audit against one regulatory standard * pharaoh-coverage-gap — single-category gap detector with explicit detection rule * pharaoh-process-audit — full-corpus gap audit across 10 categories Each decomposes into atomic checks; composable with the tailor-review layer for a standards-ready audit chain.
Chain the req→arch→vplan→fmea primitives with per-step reviews and explicit handoff contracts. First public orchestrator demonstrating composition of the atomic skills.
pharaoh-author and pharaoh-verify are replaced by the atomic chain (pharaoh-req-draft → pharaoh-req-review → pharaoh-req-regenerate, and similar for arch/vplan/fmea). Cross-references updated in pharaoh-change/decide/mece/plan/release/setup/spec/trace SKILL.md and in shared/strictness.md. CHANGELOG, CONTRIBUTING, README refreshed for the atomic-skills architecture.
Atomic retrieval skill: reads rationale memories from a Papyrus
workspace and returns a structured list of {memory_id, text,
relevance_score}. Does not draft, review, or modify artefacts.
Uses Papyrus semantic mode (cosine over sentence-transformers
all-MiniLM-L6-v2 via the [semantic] extra) — feature_context is
passed verbatim as the query, scores and memory_ids parsed from
the fenced output. Workspace detection via presence of .papyrus/
directory; missing workspace returns [] (not an error).
Sits upstream of any draft skill; inserts retrieved rationale into
the draft's input context so prior design decisions are respected.
Primitives and orchestrator for parallel audit of an existing corpus,
with shared-memory deduplication of findings across subagents:
* pharaoh-finding-record — atomic write+dedup primitive for
audit findings (one finding per call,
dedup on canonical finding signature)
* pharaoh-review-completeness — per-axis review/approval auditor
(coverage over required review axes)
* pharaoh-audit-fanout — orchestrate parallel audit subagents
over disjoint artefact ranges, shared
Papyrus as the findings ledger
Primitives and orchestrator for reverse-engineering an existing code
module into sphinx-needs requirements, with shared-memory canonical
vocabulary across parallel subagents:
* pharaoh-decision-record — atomic write+dedup for design decisions
(type, canonical_name) dedup key;
generalization of finding-record for
design-rationale memories
* pharaoh-req-from-code — reverse-engineer a single source file
into sphinx-needs comp_req directives;
calls pharaoh-context-gather before
naming types so canonical vocabulary is
reused across subagents instead of
re-coined
* pharaoh-reqs-from-module — orchestrate parallel req-from-code
subagents over files of a module, with
shared Papyrus workspace acting as the
cross-agent canonical-naming ledger
There was a problem hiding this comment.
Pull request overview
Refactors Pharaoh’s skill set toward atomic, single-artefact skills; retires the legacy composite verification skill; and introduces first-class project tailoring and Papyrus-based memory primitives to support semantic recall + deduplicated shared writes.
Changes:
- Replaces legacy verification/authoring references with an atomic author/review chain (req/arch/vplan/fmea + reviews).
- Adds tailoring bootstrap + validation skills (
tailor-detect/fill/review) and a Score example tailoring bundle + schemas. - Adds new audit/process orchestration skills (coverage gap detection, lifecycle checks, process audit, fan-out orchestrators) and Papyrus memory primitives.
Reviewed changes
Copilot reviewed 46 out of 46 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/shared/strictness.md | Updates workflow gate docs to refer to “any authoring/review skill” instead of legacy monoliths. |
| skills/pharaoh-vplan-review/SKILL.md | Adds atomic test-case review spec (per-axis JSON findings). |
| skills/pharaoh-vplan-draft/SKILL.md | Adds atomic test-case drafting spec for a single parent. |
| skills/pharaoh-verify/SKILL.md | Removes the legacy monolithic verification skill. |
| skills/pharaoh-trace/SKILL.md | Updates guidance text to point to appropriate authoring skills post-refactor. |
| skills/pharaoh-tailor-review/SKILL.md | Adds tailoring validator spec (schema + cross-file checks). |
| skills/pharaoh-tailor-fill/SKILL.md | Adds tailoring authoring spec (writes .pharaoh/project/ files). |
| skills/pharaoh-tailor-detect/SKILL.md | Adds tailoring detection spec (derives conventions from needs.json). |
| skills/pharaoh-spec/SKILL.md | Updates spec-generation plan table examples to the new skill naming. |
| skills/pharaoh-setup/SKILL.md | Updates setup docs to list the new atomic skills instead of legacy monoliths. |
| skills/pharaoh-review-completeness/SKILL.md | Adds an audit primitive to detect missing review/approval chain fields. |
| skills/pharaoh-reqs-from-module/SKILL.md | Adds orchestrator for parallel reverse-engineering from source files with shared Papyrus workspace. |
| skills/pharaoh-req-review/SKILL.md | Adds atomic requirement review spec (per-axis JSON findings). |
| skills/pharaoh-req-regenerate/SKILL.md | Adds atomic requirement regeneration spec consuming req-review findings. |
| skills/pharaoh-req-from-code/SKILL.md | Adds atomic reverse-engineering skill with Papyrus terminology coordination. |
| skills/pharaoh-req-draft/SKILL.md | Adds atomic requirement drafting spec (single directive emitted). |
| skills/pharaoh-release/SKILL.md | Updates release gating/tips to reference “review skills” rather than legacy verify. |
| skills/pharaoh-process-audit/SKILL.md | Adds full-corpus audit orchestrator aggregating coverage-gap categories. |
| skills/pharaoh-plan/SKILL.md | Updates planning docs/examples to the new author/review chain terminology. |
| skills/pharaoh-mece/SKILL.md | Updates MECE vs verification wording to align with new review skills. |
| skills/pharaoh-lifecycle-check/SKILL.md | Adds deterministic lifecycle legality checker against workflows.yaml. |
| skills/pharaoh-fmea/SKILL.md | Adds atomic FMEA row derivation spec (JSON output). |
| skills/pharaoh-flow/SKILL.md | Adds V-model orchestrator chaining req→arch→vplan→fmea plus reviews. |
| skills/pharaoh-finding-record/SKILL.md | Adds Papyrus-backed deterministic dedup write primitive for audit findings. |
| skills/pharaoh-decision-record/SKILL.md | Adds Papyrus-backed deterministic dedup write primitive for canonical decisions/facts/preferences. |
| skills/pharaoh-decide/SKILL.md | Removes delegation to legacy author skill and updates “next step” guidance to req-review. |
| skills/pharaoh-coverage-gap/SKILL.md | Adds single-category gap detector returning structured matches. |
| skills/pharaoh-context-gather/SKILL.md | Adds Papyrus semantic recall primitive for pre-draft context retrieval. |
| skills/pharaoh-change/SKILL.md | Updates change-analysis gating language to apply to all authoring skills. |
| skills/pharaoh-audit-fanout/SKILL.md | Adds orchestrator running multiple audit skills in parallel with Papyrus dedup. |
| skills/pharaoh-arch-review/SKILL.md | Adds atomic architecture-element review spec (per-axis JSON findings). |
| skills/pharaoh-arch-draft/SKILL.md | Adds atomic architecture-element drafting spec. |
| examples/score/.pharaoh/project/workflows.yaml | Adds Score example workflows configuration. |
| examples/score/.pharaoh/project/schemas/workflows.schema.json | Adds JSON schema for workflows.yaml. |
| examples/score/.pharaoh/project/schemas/id-conventions.schema.json | Adds JSON schema for id-conventions.yaml. |
| examples/score/.pharaoh/project/schemas/checklists-frontmatter.schema.json | Adds JSON schema for checklist frontmatter. |
| examples/score/.pharaoh/project/schemas/artefact-catalog.schema.json | Adds JSON schema for artefact-catalog.yaml. |
| examples/score/.pharaoh/project/id-conventions.yaml | Adds Score example ID conventions. |
| examples/score/.pharaoh/project/checklists/requirement.md | Adds Score example requirement checklist. |
| examples/score/.pharaoh/project/artefact-catalog.yaml | Adds Score example artefact catalog. |
| README.md | Updates public docs to describe the atomic skill architecture and new skill taxonomy. |
| CONTRIBUTING.md | Updates repository structure listing to include new skills. |
| CHANGELOG.md | Documents removal of legacy monoliths and addition of atomic skills. |
| .github/ISSUE_TEMPLATE/feature_request.md | Updates template hint to reference new skill names. |
* 23 skill SKILL.md descriptions rewritten to begin with
"Use when ..." per the repo's frontmatter convention
(CI step "Validate skill frontmatter").
* 23 matching agent files created in .github/agents/ for the skills
added in this branch (CI step "Cross-reference skills and
agents" requires pharaoh-X/ <-> pharaoh.X.agent.md). Agent files
are minimal stubs pointing to the SKILL.md for full behavior;
handoffs left empty since atomic primitives are invoked by
orchestrator skills, not as user-facing entry agents.
* .github/agents/pharaoh.author.agent.md and
.github/agents/pharaoh.verify.agent.md removed, since the
corresponding skills were retired in this branch.
No behavior change in the skills themselves — only frontmatter /
accompanying metadata to satisfy the CI validator.
bburda
force-pushed
the
refactor/atomic-skills
branch
from
a14250f to
dcdc68d
Compare
* shared/strictness.md — generalize "Skills with no gates" to cover
all review/audit skills, read-only memory skills, and tailor-
authoring skills; previous list only named pharaoh:req-review and
implied the other review skills had prerequisites.
* shared/strictness.md — add Section 0 clarifying that session-state
gating is an orchestrator concern. Atomic primitives do not read
pharaoh.toml or .pharaoh/session.json, do not block on gates, and
do not write session state. Orchestrators (pharaoh:flow,
audit-fanout, reqs-from-module, plan, change, release, and the
legacy top-level skills) own the gating lifecycle. This preserves
atomicity of the primitives (criterion a).
* examples/score id-conventions.yaml — add arch and tc prefix
entries; without them the example tailoring fails pharaoh-tailor-
review cross-file check C1 (every artefact-catalog key must be
declared in id-conventions.prefixes).
* examples/score checklists/requirement.md — add schema-compliant
YAML frontmatter (name / applies_to / axes per checklists-
frontmatter.schema.json) and use the canonical axis keys
(unambiguity_prose, internal_consistency, no_duplication) that
pharaoh-req-review emits.
* pharaoh-spec, pharaoh-plan — example plan tables no longer
misdirect users to pharaoh:req-draft for spec/impl/tc updates.
Spec and impl entries now point to pharaoh:arch-draft; tc entries
to pharaoh:vplan-draft; review step enumerates per-type review
skills.
* pharaoh-tailor-review — align the skill spec with the authoritative
JSON schemas and example tailoring. Fixes: workflows.yaml
lifecycle_states is an array (not a map); id_regex_exceptions is
optional (not required); checklist frontmatter is optional and
uses schema keys (name / applies_to / axes);
artefact-catalog.required_body_sections added to the structural
table; C2/C3 rule wording updated for array semantics.
* pharaoh-vplan-draft, pharaoh-vplan-review — separate directive-
option keys (required_fields) from body-prose section headings
(required_body_sections). Previous spec treated inputs / steps /
expected as directive options, which contradicted the Score
tailoring and the artefact-catalog schema. Defaults now align:
required_fields = [id, status, verifies],
required_body_sections = [Inputs, Steps, Expected].
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refactor of Pharaoh into atomic single-artefact skills, retirement of the legacy
pharaoh-author/pharaoh-verifycomposite skills, and first-class Papyrus memory integration (semantic retrieval + shared write primitive).What this adds
pharaoh-req-{draft,review,regenerate},pharaoh-arch-{draft,review},pharaoh-vplan-{draft,review},pharaoh-fmea— each produces or audits a single artefact against one axis.pharaoh-context-gather(read via Papyrus semantic recall overall-MiniLM-L6-v2embeddings),pharaoh-decision-recordandpharaoh-finding-record(atomic write with(type, canonical_name)dedup key).pharaoh-flowchains req→arch→vplan→fmea with per-step reviews;pharaoh-audit-fanoutfans out parallel auditors over disjoint artefact ranges;pharaoh-reqs-from-modulefans out parallel reverse-engineering subagents over source files.pharaoh-tailor-{detect,fill,review}plus JSON schemas for.pharaoh/project/(artefact-catalog,id-conventions,checklists,workflows) — per-project content lives here; domain skills stay generic.pharaoh-lifecycle-check,pharaoh-standard-conformance,pharaoh-coverage-gap,pharaoh-process-audit— cross-cutting gap / conformance audits over an existing corpus.examples/score/.pharaoh/project/exercises the primitives against a realistic safety-critical layout.pharaoh-authorandpharaoh-verifyremoved; cross-references across remaining skills updated;README/CONTRIBUTING/CHANGELOGrefreshed for the atomic architecture.Design notes
papyrus[semantic]extra is available forpharaoh-context-gather's semantic recall; without it the skill returns[]gracefully (non-blocking for downstream drafts).pharaoh-req-from-codeexplicitly callspharaoh-context-gatherbefore naming any type in an emitted requirement, so parallel subagents can reuse canonical vocabulary via the shared workspace instead of re-coining synonyms.Commit layout
8 commits grouped by logical area (core authoring primitives → tailoring → process-audit →
pharaoh-flow→ retirement of legacy skills → memory retrieval → parallel review → parallel reverse-engineering). Each commit is self-contained and can be reviewed independently.Test plan
pharaoh-authorcontinue to work after retirement (cross-reference check)pharaoh-context-gatheragainst a workspace without the[semantic]extra returns[]without crashingpharaoh-context-gatheragainst a freshlypapyrus init-ed (empty) workspace returns[]pharaoh-reqs-from-moduleon a small module with shared Papyrus completes without concurrent-write errorspharaoh-tailor-reviewpasses schema validation onexamples/score/.pharaoh/project/