@mrciphersmith/keryx 0.2.72 → 0.2.74

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"
+name: spec-writer
+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.

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.cursor.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"
+name: spec-writer
+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.

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

@@ -1,5 +1,5 @@
 ---
-name: gproject-spec-writer
+name: spec-writer
 description: >
   Generates PRD or Implementation Plan constrained by decisions registry,
   architecture doc, and best practices. Does NOT invent new architectural decisions.

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.codex.md

@@ -1,18 +1,15 @@
 ---
-name: gproject-stack-advisor
-description: "Determines project level (MVP/pet/startup/production) and recommends optimal technology stack with trade-off analysis. Use when: dispatched by gproject-orchestrator Phase 2."
-triggers:
-  - "gproject-stack-advisor: select stack"
-  - "Dispatched by gproject-orchestrator Phase 2"
+name: stack-advisor
+description: >
+  Determines project level (MVP/pet/startup/production) and recommends optimal
+  technology stack with trade-off analysis.
+  Use when: dispatched by gproject-orchestrator Phase 2.
+  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-stack-advisor
 
 ## Purpose
@@ -41,3 +38,158 @@ with trade-offs — not "use React because it's popular" but "use React because
 | Ignoring team skills in rationale | Tech-driven not people-driven | Re-evaluate with team factor |
 | No alternative considered | Confirmation bias | Research at least 1 alternative per choice |
 | Recommending bleeding-edge for production | Risk ignorance | Flag maturity concern |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Select project level and technology stack"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/problem-statement.md
+decisions_so_far:
+  D_core_problems: [...]
+  D_goals: [...]
+  D_non_goals: [...]
+  D_target_users: "..."
+  D_scale_estimate: "..."
+  # For task_in_project:
+  D_existing_stack: "<if detected by context-collector>"
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: level chosen, stack chosen, key trade-off>"
+new_decisions:
+  D_level: "mvp | pet | startup | production"
+  D_frontend: "<framework + version>"
+  D_backend: "<framework + version>"
+  D_database: "<DB + version>"
+  D_cache: "<if needed>"
+  D_queue: "<if needed>"
+  D_auth: "<approach>"
+  D_deploy: "<strategy>"
+  D_infra: "<approach>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/stack-decision.md"
+next_phase_needs:
+  - "Per-technology best practices research"
+  - "Architecture pattern selection"
+```
+
+---
+
+## Workflow
+
+### Step 1: Determine Project Level
+
+Evaluate against criteria matrix:
+
+| Factor | MVP | Pet/Learning | Startup | Production |
+|--------|-----|-------------|---------|------------|
+| Users | <100 | 1 (self) | 100-10K | 10K+ |
+| Team | 1 person | 1 person | 2-5 | 5+ |
+| Lifespan | weeks | indefinite | months-years | years |
+| Budget | minimal | zero | seed/limited | funded |
+| Uptime SLA | none | none | 99% | 99.9%+ |
+| Data sensitivity | low | low | medium | high |
+| Compliance | none | none | basic | regulated |
+
+The level determines complexity ceiling:
+- **MVP**: max simplicity, monolith, single deploy target, minimal infra
+- **Pet**: developer experience priority, learning-friendly stack
+- **Startup**: balance of speed and scalability, ready for growth
+- **Production**: reliability, security, observability, scalability first
+
+### Step 2: Evaluate Stack Options
+
+For each layer, evaluate 2-3 options against project-specific criteria:
+
+**Evaluation criteria** (weight varies by project level):
+1. **Problem fit** — does it solve our specific problems well?
+2. **Team match** — does the team know it? Learning curve?
+3. **Ecosystem** — libraries, tools, community for our use case
+4. **Scalability ceiling** — will it handle our target scale?
+5. **Velocity** — how fast can we ship with it?
+6. **Cost** — licensing, hosting, operational cost
+7. **Maturity** — production-proven? Active maintenance?
+8. **Integration** — works well with other chosen components?
+
+### Step 3: Web Research (Best Practices)
+
+For the shortlisted stack, research:
+- Current best practices (2024-2025 sources preferred)
+- Common pitfalls and antipatterns
+- Production case studies at similar scale
+- Performance benchmarks relevant to our use case
+
+### Step 4: task_in_project Mode Adjustments
+
+If mode is task_in_project:
+- Start from existing stack (detected by context-collector)
+- Only recommend NEW technologies if:
+  - Existing stack cannot solve the specific problem
+  - New tech integrates cleanly with existing stack
+  - Learning overhead is justified by benefit
+- Flag any technology additions clearly as "NEW — requires team learning"
+
+### Step 5: Write Stack Decision
+
+Write `artifacts/stack-decision.md`:
+
+```markdown
+# Stack Decision: <Project/Task Name>
+
+## Project Level: <LEVEL>
+**Rationale**: <why this level, based on constraints>
+
+## Technology Stack
+
+### Frontend: <Choice>
+**Version**: <specific>
+**Rationale**: <tied to project constraints>
+**Alternative considered**: <what and why rejected>
+**Key libraries**: <essential deps>
+
+### Backend: <Choice>
+**Version**: <specific>
+**Rationale**: <tied to project constraints>
+**Alternative considered**: <what and why rejected>
+**Key libraries**: <essential deps>
+
+### Database: <Choice>
+...
+
+### Infrastructure & Deploy: <Choice>
+...
+
+### Additional Services (if any)
+- Cache: <if needed, with rationale>
+- Queue: <if needed, with rationale>
+- Search: <if needed, with rationale>
+
+## Stack Compatibility Matrix
+| Component | Integrates With | Integration Quality |
+|-----------|----------------|-------------------|
+| <A> | <B> | proven / good / experimental |
+
+## Trade-offs Accepted
+| Trade-off | What We Gain | What We Give Up |
+|-----------|-------------|-----------------|
+| <choice> | <benefit> | <cost> |
+
+## Complexity Budget
+**Total new technologies**: <count>
+**Team learning required**: <list what's new>
+**Estimated ramp-up**: <time>
+
+## Risk Assessment
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| <risk> | <H/M/L> | <H/M/L> | <plan> |
+```
+
+### Step 6: Return Summary
+
+Compact summary: level + core stack (one line) + biggest trade-off + confidence.