@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/skills/planning/prd-creator/output-contract.schema.json

@@ -0,0 +1,175 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "prd-creator-output-contract",
+    "title": "PRD-Creator Output Contract",
+    "description": "Defines the output structure for the PRD-Creator skill, which can be either clarification questions or a completed PRD.",
+    "type": "object",
+    "required": [
+        "status"
+    ],
+    "properties": {
+        "status": {
+            "type": "string",
+            "enum": [
+                "needs_clarification",
+                "completed"
+            ],
+            "description": "The status of the PRD formulation process."
+        },
+        "questions": {
+            "type": "array",
+            "description": "List of clarification questions. Present if status is 'needs_clarification'.",
+            "items": {
+                "type": "object",
+                "required": [
+                    "id",
+                    "type",
+                    "question"
+                ],
+                "properties": {
+                    "id": {
+                        "type": "string"
+                    },
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "multiple_choice",
+                            "open_text"
+                        ]
+                    },
+                    "question": {
+                        "type": "string"
+                    },
+                    "options": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "description": "Available options for multiple_choice questions."
+                    }
+                }
+            }
+        },
+        "prd": {
+            "type": "object",
+            "description": "The finalized Product Requirements Document. Present if status is 'completed'.",
+            "required": [
+                "overview",
+                "context",
+                "problemStatement",
+                "goals",
+                "functionalRequirements",
+                "nonFunctionalRequirements",
+                "acceptanceCriteria",
+                "verification"
+            ],
+            "properties": {
+                "overview": {
+                    "type": "string"
+                },
+                "context": {
+                    "type": "object"
+                },
+                "problemStatement": {
+                    "type": "string"
+                },
+                "goals": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "nonGoals": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "functionalRequirements": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "nonFunctionalRequirements": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "constraints": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "edgeCases": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "acceptanceCriteria": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Gherkin format Given/When/Then scenarios."
+                },
+                "verification": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "qualityScore": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 10,
+            "description": "Internal quality score of the generated PRD."
+        },
+        "riskAssessment": {
+            "type": "string",
+            "enum": [
+                "low",
+                "medium",
+                "high"
+            ],
+            "description": "Assessed risk level of the feature based on the PRD."
+        }
+    },
+    "allOf": [
+        {
+            "if": {
+                "properties": {
+                    "status": {
+                        "const": "needs_clarification"
+                    }
+                }
+            },
+            "then": {
+                "required": [
+                    "questions"
+                ]
+            }
+        },
+        {
+            "if": {
+                "properties": {
+                    "status": {
+                        "const": "completed"
+                    }
+                }
+            },
+            "then": {
+                "required": [
+                    "prd",
+                    "qualityScore",
+                    "riskAssessment"
+                ]
+            }
+        }
+    ]
+}

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.codex.md

@@ -0,0 +1,31 @@
+---
+name: gproject-problem-definer
+description: "Defines core problems, SMART goals, non-goals, and success metrics from discovery data. Use when: dispatched by gproject-orchestrator Phase 1."
+triggers:
+  - "gproject-problem-definer: define problems and goals"
+  - "Dispatched by gproject-orchestrator Phase 1"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "planning"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+
+# gproject-problem-definer
+
+## Purpose
+
+Transform raw discovery data into a crisp problem statement with measurable goals.
+This phase answers: "Why are we doing this?" and "How will we know we succeeded?"
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Every goal MUST have a measurable success metric |
+| 2 | Non-goals are as important as goals — list at least 3 |
+| 3 | Problems MUST be stated from the USER's perspective, not technical |
+| 4 | NEVER introduce solutions in the problem statement |
+| 5 | If discovery brief has low confidence areas, flag them — don't paper over |

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.cursor.md

@@ -0,0 +1,31 @@
+---
+name: gproject-problem-definer
+description: "Defines core problems, SMART goals, non-goals, and success metrics from discovery data. Use when: dispatched by gproject-orchestrator Phase 1."
+triggers:
+  - "gproject-problem-definer: define problems and goals"
+  - "Dispatched by gproject-orchestrator Phase 1"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "planning"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+
+# gproject-problem-definer
+
+## Purpose
+
+Transform raw discovery data into a crisp problem statement with measurable goals.
+This phase answers: "Why are we doing this?" and "How will we know we succeeded?"
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Every goal MUST have a measurable success metric |
+| 2 | Non-goals are as important as goals — list at least 3 |
+| 3 | Problems MUST be stated from the USER's perspective, not technical |
+| 4 | NEVER introduce solutions in the problem statement |
+| 5 | If discovery brief has low confidence areas, flag them — don't paper over |

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: gproject-problem-definer
+description: >
+  Defines core problems, goals, non-goals, and success metrics from discovery data.
+  Use when: dispatched by gproject-orchestrator Phase 1.
+  NOT for: direct user invocation.
+version: 1.0.0
+---
+
+# gproject-problem-definer
+
+## Purpose
+
+Transform raw discovery data into a crisp problem statement with measurable goals.
+This phase answers: "Why are we doing this?" and "How will we know we succeeded?"
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | Every goal MUST have a measurable success metric |
+| 2 | Non-goals are as important as goals — list at least 3 |
+| 3 | Problems MUST be stated from the USER's perspective, not technical |
+| 4 | NEVER introduce solutions in the problem statement |
+| 5 | If discovery brief has low confidence areas, flag them — don't paper over |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Define core problems and goals"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/discovery-brief.md
+decisions_so_far:
+  D_mode: "..."
+  D_domain: "..."
+  D_audience: "..."
+  D_scale_estimate: "..."
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: core problem, primary goal, key constraint>"
+new_decisions:
+  D_core_problems: ["<problem 1>", "<problem 2>"]
+  D_goals: ["<goal 1 + metric>", "<goal 2 + metric>"]
+  D_non_goals: ["<non-goal 1>", "<non-goal 2>", "<non-goal 3>"]
+  D_success_metrics: ["<metric 1>", "<metric 2>"]
+  D_target_users: "<primary persona>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/problem-statement.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Extract Problems
+
+From discovery brief, identify:
+- What pain points do target users have?
+- What's broken / missing / inefficient?
+- What opportunity exists?
+
+Frame each problem as: "**[User type]** cannot / struggles to **[action]** because **[reason]**, which results in **[consequence]**."
+
+### Step 2: Define Goals (SMART)
+
+For each problem, define a goal:
+- **Specific** — exactly what will change
+- **Measurable** — quantifiable success metric
+- **Achievable** — realistic given constraints
+- **Relevant** — tied to a real problem
+- **Time-bound** — when to evaluate (if applicable)
+
+### Step 3: Define Non-Goals (Critical)
+
+Explicitly state what this project will NOT do. This prevents scope creep
+and aligns expectations. Common categories:
+- Features explicitly excluded from scope
+- User segments not targeted
+- Performance levels not targeted (e.g., "not optimized for 1M+ users")
+- Platforms not supported
+- Integrations not included
+
+### Step 4: Define Success Metrics
+
+For each goal, define how to measure success:
+- Quantitative metrics (response time, conversion rate, error rate)
+- Qualitative metrics (user satisfaction, NPS)
+- Leading indicators (usage frequency, feature adoption)
+
+### Step 5: Write Problem Statement
+
+Write `artifacts/problem-statement.md`:
+
+```markdown
+# Problem Statement: <Project/Task Name>
+
+## Core Problems
+### P1: <Problem Title>
+<User type> cannot <action> because <reason>, resulting in <consequence>.
+**Impact**: <high/medium/low>
+**Evidence**: <from discovery brief>
+
+### P2: ...
+
+## Goals
+### G1: <Goal Title>
+**Statement**: <SMART goal>
+**Success Metric**: <measurable metric>
+**Target**: <specific target value>
+**Measured by**: <how and when>
+
+### G2: ...
+
+## Non-Goals
+### NG1: <Non-Goal>
+**Why excluded**: <rationale>
+
+### NG2: ...
+### NG3: ...
+
+## Target Users
+### Primary Persona
+- **Who**: <description>
+- **Core need**: <what they need most>
+- **Current solution**: <how they solve it today>
+
+### Secondary Persona (if applicable)
+- ...
+
+## Success Criteria
+| Metric | Current State | Target | Measurement Method |
+|--------|--------------|--------|-------------------|
+| <metric> | <baseline or N/A> | <target> | <how to measure> |
+
+## Assumptions & Risks
+| Assumption | Risk if Wrong | Mitigation |
+|-----------|--------------|------------|
+| <assumption> | <impact> | <what to do> |
+
+## Scope Boundary
+**In scope**: <brief list>
+**Out of scope**: <brief list referencing non-goals>
+```
+
+### Step 6: Return Summary
+
+Return compact summary to orchestrator: core problem in one sentence,
+primary goal in one sentence, biggest risk, confidence level.

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.codex.md

@@ -0,0 +1,32 @@
+---
+name: gproject-discovery
+description: "Collects and structures initial project information from user input, documents, codebase, and web research. Use when: dispatched by gproject-orchestrator Phase 0."
+triggers:
+  - "gproject-discovery: collect project data"
+  - "Dispatched by gproject-orchestrator Phase 0"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "planning"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+
+# gproject-discovery
+
+## Purpose
+
+Gather raw project information from all available sources, structure it into
+a unified discovery brief. This is the foundation — every downstream decision
+depends on the quality of discovery.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | NEVER assume information not explicitly provided or discovered |
+| 2 | ALWAYS distinguish facts from assumptions — label each |
+| 3 | If a critical area has no data, return NEEDS_CONTEXT — don't fill gaps with guesses |
+| 4 | Web research MUST cite sources |
+| 5 | Codebase analysis MUST reference actual file paths |

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.cursor.md

@@ -0,0 +1,32 @@
+---
+name: gproject-discovery
+description: "Collects and structures initial project information from user input, documents, codebase, and web research. Use when: dispatched by gproject-orchestrator Phase 0."
+triggers:
+  - "gproject-discovery: collect project data"
+  - "Dispatched by gproject-orchestrator Phase 0"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "planning"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+
+# gproject-discovery
+
+## Purpose
+
+Gather raw project information from all available sources, structure it into
+a unified discovery brief. This is the foundation — every downstream decision
+depends on the quality of discovery.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | NEVER assume information not explicitly provided or discovered |
+| 2 | ALWAYS distinguish facts from assumptions — label each |
+| 3 | If a critical area has no data, return NEEDS_CONTEXT — don't fill gaps with guesses |
+| 4 | Web research MUST cite sources |
+| 5 | Codebase analysis MUST reference actual file paths |

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: gproject-discovery
+description: >
+  Collects and structures initial project information from multiple sources.
+  Use when: dispatched by gproject-orchestrator Phase 0.
+  NOT for: direct user invocation — always called through orchestrator.
+version: 1.0.0
+---
+
+# gproject-discovery
+
+## Purpose
+
+Gather raw project information from all available sources, structure it into
+a unified discovery brief. This is the foundation — every downstream decision
+depends on the quality of discovery.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | NEVER assume information not explicitly provided or discovered |
+| 2 | ALWAYS distinguish facts from assumptions — label each |
+| 3 | If a critical area has no data, return NEEDS_CONTEXT — don't fill gaps with guesses |
+| 4 | Web research MUST cite sources |
+| 5 | Codebase analysis MUST reference actual file paths |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Collect project discovery data"
+mode: "new_project" | "task_in_project"
+user_input: "<original user request text>"
+uploaded_docs: [<file paths if any>]
+repo_path: "<path if task_in_project>"
+interview_results: "<from interview skill, if already run>"
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: what was found, key gaps, confidence level>"
+new_decisions:
+  D_mode: "new_project | task_in_project"
+  D_domain: "<business domain>"
+  D_audience: "<target users>"
+  D_scale_estimate: "<rough scale: personal/team/startup/enterprise>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/discovery-brief.md"
+```
+
+If NEEDS_CONTEXT:
+```yaml
+status: "NEEDS_CONTEXT"
+questions:
+  - id: "Q1"
+    text: "<question>"
+    options:
+      A: "<option>"
+      B: "<option>"
+      C: "<option>"
+      D: "<option>"
+    why: "<why this matters for downstream phases>"
+```
+
+---
+
+## Workflow
+
+### Step 1: Parse User Input
+
+Extract from the user's original request:
+- What they want to build/implement
+- Any constraints mentioned (budget, timeline, team size)
+- Any technical preferences mentioned
+- Target audience / users mentioned
+
+### Step 2: Source-Specific Collection
+
+#### Mode: new_project
+
+1. **User input analysis** — extract all explicit and implied requirements
+2. **Uploaded documents** — parse any attached files (briefs, notes, mockups, transcripts)
+3. **Web research** — search for:
+   - Similar products / competitors (max 5)
+   - Market context and trends
+   - Common technical approaches for this type of project
+4. **Gap identification** — list what's missing for confident decision-making
+
+#### Mode: task_in_project
+
+1. **User input analysis** — extract the specific task/feature request
+2. **Codebase scan** (via context-collector) — gather:
+   - Project structure (directories, key files)
+   - Technology stack (package.json, requirements.txt, Dockerfile, etc.)
+   - Architecture patterns in use
+   - Existing documentation (README, docs/, ADRs)
+   - Related code areas (files likely affected by this task)
+3. **Existing docs** — parse project documentation for context
+4. **Web research** — best practices for the specific task within the detected stack
+5. **Gap identification** — what's unclear about the existing codebase or requirements
+
+### Step 3: Structure Discovery Brief
+
+Write `artifacts/discovery-brief.md` with this structure:
+
+```markdown
+# Discovery Brief: <Project/Task Name>
+
+## Source Summary
+- User input: <what was provided>
+- Documents analyzed: <list>
+- Codebase scanned: <yes/no, scope>
+- Web research: <topics covered>
+
+## Project/Task Description
+<Clear 2-3 paragraph description of what needs to be built/done>
+
+## Key Facts (confirmed)
+- <fact 1> [source: user input / document / codebase]
+- <fact 2> [source: ...]
+
+## Assumptions (need validation)
+- <assumption 1> — confidence: high/medium/low
+- <assumption 2> — confidence: ...
+
+## Stakeholders & Users
+- Primary users: <who>
+- Secondary users: <who>
+- Stakeholders: <who decides>
+
+## Existing Context (task_in_project only)
+- Tech stack: <detected>
+- Architecture: <detected patterns>
+- Related components: <list with file paths>
+- Existing patterns to follow: <list>
+
+## Competitive / Market Context (new_project only)
+- Similar products: <list with brief notes>
+- Differentiators mentioned: <list>
+- Market trends: <relevant>
+
+## Constraints Identified
+- Budget: <if mentioned>
+- Timeline: <if mentioned>
+- Team: <size, skills if mentioned>
+- Technical: <any mentioned constraints>
+
+## Open Questions
+- <question 1> — impacts: <which downstream decisions>
+- <question 2> — impacts: ...
+
+## Confidence Assessment
+- Overall completeness: <high/medium/low>
+- Areas needing more data: <list>
+```
+
+### Step 4: Return Summary to Orchestrator
+
+Compose compact summary (3-5 sentences) covering:
+- What the project/task is about
+- Key constraints discovered
+- Confidence level
+- Critical gaps that need resolution

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.codex.md

@@ -0,0 +1,44 @@
+---
+name: gproject-spec-writer
+description: "Generates PRD or Implementation Plan constrained by upstream decisions, architecture, and best practices. Use when: dispatched by gproject-orchestrator Phase 4."
+triggers:
+  - "gproject-spec-writer: write PRD"
+  - "Dispatched by gproject-orchestrator Phase 4"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "planning"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+
+# gproject-spec-writer
+
+## Purpose
+
+Write a comprehensive PRD (new project) or Implementation Plan (task in project)
+that is fully constrained by the decisions made in Phases 0-3. This agent
+does NOT make architectural or stack decisions — it translates existing decisions
+into actionable requirements and user stories.
+
+## Iron Laws
+
+| # | Law |
+|---|-----|
+| 1 | NEVER introduce a technology not in stack-decision.md |
+| 2 | NEVER propose an architecture pattern not in architecture.md |
+| 3 | EVERY technical requirement MUST reference a constraint from tech-bestpractices.md |
+| 4 | EVERY user story MUST trace back to a goal in problem-statement.md |
+| 5 | Non-goals from problem-statement.md MUST NOT appear as features |
+| 6 | If a requirement conflicts with a constraint, return BLOCKED — don't resolve silently |
+| 7 | User stories MUST have testable acceptance criteria |
+
+## Red Flags
+
+| Flag | What's happening | Action |
+|------|-----------------|--------|
+| Writing "we'll use X" where X is not in stack decisions | Introducing undecided tech | STOP → check stack-decision.md |
+| User story without acceptance criteria | Untestable requirement | STOP → add criteria or flag as incomplete |
+| Feature that contradicts a non-goal | Scope creep | STOP → remove or flag as conflict |
+| Technical spec section with no BP constraint reference | Unconstrained decision | STOP → find applicable constraint or flag gap |