@mrciphersmith/keryx 0.2.72 → 0.2.73

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

@@ -1,18 +1,14 @@
 ---
 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"
+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.
 metadata:
-  author: "MrCipherSmith"
-  version: "1.0.0"
-  category: "planning"
+  version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
-license: "MIT"
 ---
 
-
 # gproject-discovery
 
 ## Purpose
@@ -30,3 +26,143 @@ depends on the quality of discovery.
 | 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/project-discovery/SKILL.cursor.md

@@ -1,18 +1,14 @@
 ---
 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"
+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.
 metadata:
-  author: "MrCipherSmith"
-  version: "1.0.0"
-  category: "planning"
+  version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
-license: "MIT"
 ---
 
-
 # gproject-discovery
 
 ## Purpose
@@ -30,3 +26,143 @@ depends on the quality of discovery.
 | 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

@@ -1,18 +1,15 @@
 ---
 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"
+description: >
+  Generates PRD or Implementation Plan constrained by decisions registry,
+  architecture doc, and best practices. Does NOT invent new architectural decisions.
+  Use when: dispatched by gproject-orchestrator Phase 4.
+  NOT for: direct user invocation.
 metadata:
-  author: "MrCipherSmith"
-  version: "1.0.0"
-  category: "planning"
+  version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
-license: "MIT"
 ---
 
-
 # gproject-spec-writer
 
 ## Purpose
@@ -42,3 +39,207 @@ into actionable requirements and user stories.
 | 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 |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Generate PRD / Implementation Plan"
+mode: "new_project" | "task_in_project"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/problem-statement.md
+  - .metaproject/jobs/<job>/artifacts/architecture.md
+  - .metaproject/jobs/<job>/artifacts/tech-bestpractices.md
+  - .metaproject/jobs/<job>/decisions.md
+decisions_so_far: <all decisions from D1 through D_arch_pattern>
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "DONE_WITH_CONCERNS" | "BLOCKED"
+summary: "<3-5 sentences: document type, user story count, key scope decisions>"
+new_decisions: {}  # PRD does NOT add architectural decisions
+concerns: ["<if DONE_WITH_CONCERNS — gaps or ambiguities found>"]
+artifact_path: ".metaproject/jobs/<job>/artifacts/prd.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Validate Inputs
+
+Before writing anything, verify:
+- [ ] All referenced decisions exist in decisions.md
+- [ ] No contradictions between problem-statement and architecture
+- [ ] Best practices constraints are internally consistent
+- [ ] Scope (goals + non-goals) is clear
+
+If validation fails → return `STATUS: BLOCKED` with specific issues.
+
+### Step 2: Determine Document Type
+
+```
+IF mode == "new_project":
+  → Write full PRD (template A below)
+ELSE IF mode == "task_in_project":
+  → Write Implementation Plan (template B below)
+```
+
+### Step 3: Write User Stories
+
+For each goal in problem-statement.md, generate user stories:
+
+Format:
+```
+### US-<NNN>: <Title>
+**As a** <user type from D_target_users>
+**I want to** <action>
+**So that** <benefit tied to goal G_N>
+
+**Acceptance Criteria:**
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+
+**Technical Notes:**
+- Constraint ref: <reference to tech-bestpractices.md constraint>
+- Architecture ref: <reference to architecture.md section>
+
+**Priority:** P0 (must-have) | P1 (should-have) | P2 (nice-to-have)
+```
+
+Prioritization rules:
+- **P0**: directly solves a core problem (P1/P2 in problem-statement)
+- **P1**: supports a goal but not critical for launch
+- **P2**: enhances experience, can be deferred
+
+### Step 4: Write Document
+
+#### Template A: Full PRD (new_project)
+
+```markdown
+# PRD: <Project Name>
+
+## Document Metadata
+- **Based on**: problem-statement.md, architecture.md, tech-bestpractices.md
+- **Decisions referenced**: <list of D_* IDs>
+- **Generated by**: gproject-spec-writer v1.0.0
+
+## Executive Summary
+<2-3 paragraphs: what, why, for whom, high-level how>
+
+## Goals & Success Metrics
+<from problem-statement.md — reference, don't duplicate>
+| Goal ID | Goal | Success Metric | Target |
+|---------|------|---------------|--------|
+| G1 | <goal> | <metric> | <target> |
+
+## Non-Goals
+<from problem-statement.md — reference explicitly>
+
+## Technical Foundation
+**Stack**: <from stack-decision.md — summarize, don't duplicate>
+**Architecture**: <from architecture.md — summarize>
+**Key Constraints**: <from tech-bestpractices.md — list MUST constraints>
+
+## User Stories
+
+### Epic 1: <Epic Name>
+<Group of related user stories>
+
+#### US-001: <Title>
+...
+
+### Epic 2: <Epic Name>
+...
+
+## Data Model (High-Level)
+<Key entities and relationships — aligned with DB constraints from BP>
+
+## API Surface (High-Level)
+<Key endpoints/operations — aligned with API constraints from BP>
+
+## Security Requirements
+<Aligned with security constraints from BP>
+
+## Testing Requirements
+<Aligned with testing constraints from BP — reference test pyramid targets>
+
+## Out of Scope
+<Explicit reference to non-goals + any additional scope exclusions>
+
+## Open Questions
+<Any remaining ambiguities — flagged for orchestrator>
+
+## Traceability Matrix
+| User Story | Goal | Problem | BP Constraint | Architecture Section |
+|-----------|------|---------|---------------|---------------------|
+| US-001 | G1 | P1 | Frontend.MUST.1 | Layer: API |
+| US-002 | G1 | P1 | Backend.MUST.3 | Layer: Service |
+```
+
+#### Template B: Implementation Plan (task_in_project)
+
+```markdown
+# Implementation Plan: <Task Name>
+
+## Document Metadata
+- **Based on**: discovery-brief.md, architecture.md, tech-bestpractices.md
+- **Existing project context**: ai/context.md
+- **Decisions referenced**: <list of D_* IDs>
+
+## Summary
+<What needs to be done, why, and how it fits into existing architecture>
+
+## Impact Analysis
+### Files Affected
+| File/Module | Change Type | Risk |
+|------------|------------|------|
+| <path> | modify / create / delete | low / medium / high |
+
+### Dependencies
+- <component X depends on this change>
+- <this change requires Y to be done first>
+
+## Implementation Steps
+
+### Step 1: <Title>
+**What**: <specific change>
+**Where**: <file paths>
+**Pattern to follow**: <reference existing project patterns>
+**BP constraint**: <reference tech-bestpractices.md>
+**Acceptance criteria**:
+- [ ] <testable criterion>
+
+### Step 2: ...
+
+## Testing Plan
+<Aligned with testing constraints — what tests to write, what coverage>
+
+## Migration / Rollback Plan (if applicable)
+<How to roll back if something goes wrong>
+
+## Traceability Matrix
+| Step | Goal | BP Constraint | Existing Pattern |
+|------|------|---------------|-----------------|
+| Step 1 | G1 | Backend.MUST.2 | existing-service.ts pattern |
+```
+
+### Step 5: Self-Validate
+
+Before returning, check:
+- [ ] Every user story traces to a goal
+- [ ] No features from non-goals list
+- [ ] Every technical note references a BP constraint
+- [ ] All acceptance criteria are testable (no "should work well")
+- [ ] Traceability matrix is complete
+
+If self-validation finds issues → fix them. If unfixable → return `DONE_WITH_CONCERNS`.
+
+### Step 6: Return Summary
+
+Compact summary: document type, total user stories / steps,
+P0 count, any concerns or gaps found during self-validation.