feat: add pharaoh:spec and pharaoh:decide skills#2
Conversation
Add decision type with decided_by, alternatives, rationale fields and decides link type. Include example decisions in decisions.rst.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the pharaoh:decide and pharaoh:spec skills to the framework, enabling the recording of traceable design decisions and the generation of specification documents with implementation plans. The update includes new agent definitions, skill documentation, and expanded configuration options in pharaoh.toml. Review feedback highlights opportunities to better align the skill logic with new configuration keys for file placement and status defaults, alongside suggestions to use the artifact style for decision needs to improve visual clarity in traceability graphs.
| title = "Decision" | ||
| prefix = "DEC_" | ||
| color = "#E8D0A9" | ||
| style = "node" |
There was a problem hiding this comment.
The suggested style for the decision type is node, but the test fixture in tests/fixtures/basic-project/ubproject.toml uses artifact. Using artifact is generally preferred for decisions to distinguish them from requirements in visual representations.
| style = "node" | |
| style = "artifact" |
| - **Standalone invocation**: Default status to `proposed`. | ||
| - **Called by `pharaoh:spec`**: Default status to `accepted`. |
There was a problem hiding this comment.
These default status values should be explicitly linked to the configuration keys default_status and spec_status from the [pharaoh.decisions] section in pharaoh.toml. This ensures the AI respects user-defined defaults when they are provided.
|
|
||
| ### Step 5: File Placement | ||
|
|
||
| Place the decision in `decisions.rst` in the same directory as the affected requirements. |
There was a problem hiding this comment.
The file placement logic should prioritize the default_file setting from pharaoh.toml if it is configured. The current description only mentions the directory-based fallback logic, which is inconsistent with the configuration options provided in pharaoh.toml.example.
| title = "Decision" | ||
| prefix = "DEC_" | ||
| color = "#E8D0A9" | ||
| style = "node" |
There was a problem hiding this comment.
For consistency with the test fixtures and better visual distinction in the needs graph, consider using style = "artifact" for the decision type instead of node.
| style = "node" | |
| style = "artifact" |
|
|
||
| ### Step 5: File Placement | ||
|
|
||
| Place in `decisions.rst` in the same directory as the first need in `:decides:`. Create the file with proper RST title if it does not exist. If no `:decides:` links, fall back to @pharaoh.author file placement. Delegate actual writing to @pharaoh.author. |
There was a problem hiding this comment.
This step should also check for the [pharaoh.decisions].default_file setting in pharaoh.toml. If configured, the decision should be placed in that file instead of defaulting to a directory-relative decisions.rst.
| - **decided_by**: `claude` (since the AI is generating the spec). | ||
| - **alternatives**: At least two alternatives considered, semicolon-separated. | ||
| - **rationale**: Why this option was chosen. | ||
| - **status**: `accepted` (decisions made during spec generation are accepted by default). |
There was a problem hiding this comment.
The default status for decisions created during spec generation should be retrieved from the spec_status configuration key in pharaoh.toml if available, rather than being hardcoded to accepted.
1 participant
Summary
decisionneed type — new sphinx-needs type withdecided_by,alternatives,rationalefields and:decides:link type, using modern[needs.fields.*]TOML syntaxpharaoh:decideskill — records design decisions as traceable needs, delegates RST writing topharaoh:author, no workflow gatespharaoh:specskill — reads requirements hierarchy, identifies coverage gaps, invokespharaoh:decidefor design choices, generates Superpowers-compatible spec doc with embedded plan table forpharaoh:planexecution@pharaoh.specand@pharaoh.decidein.github/agents/This eliminates the disconnect between sphinx-needs requirements and Claude Code + Superpowers spec/plan docs by generating specs deterministically from needs data, with decisions tracked as first-class sphinx-needs objects versioned in git.
Test plan
ubproject.tomlparses correctly (python3 -c "import tomllib; ...")pharaoh:spec REQ_001against the test fixture and confirm spec doc is generated with correct sectionspharaoh:decidestandalone and confirm decision need is written with all fields@pharaoh.specand@pharaoh.decidepharaoh:plan(7 columns including File)