@mrciphersmith/keryx 0.2.71 → 0.2.73

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Critical requirements interviewer that gathers precise context before complex tasks. Asks one focused question at a time (with A/B/C options where applicable). Skips questions already answered by provided context. Can be called by other skills as a sub-agent or directly by the user. Outputs structured context for the calling skill."
+description: "Use when requirements are ambiguous and precise clarification is needed before proceeding with a complex task."
 triggers:
   - "Interview me"
   - "Ask me questions"
@@ -15,6 +15,12 @@ metadata:
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for orchestrators and interactive session-level routing only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Interviewer
 
 ## Purpose

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Critical requirements interviewer that gathers precise context before complex tasks. Asks one focused question at a time (with A/B/C options where applicable). Skips questions already answered by provided context. Can be called by other skills as a sub-agent or directly by the user. Outputs structured context for the calling skill."
+description: "Use when requirements are ambiguous and precise clarification is needed before proceeding with a complex task."
 triggers:
   - "Interview me"
   - "Ask me questions"
@@ -15,6 +15,12 @@ metadata:
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for orchestrators and interactive session-level routing only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Interviewer
 
 ## Purpose

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.codex.md

@@ -1,18 +1,15 @@
 ---
 name: gproject-patterns-researcher
-description: "Researches per-technology best practices and defines architecture patterns that become binding PRD constraints. Use when: dispatched by gproject-orchestrator Phase 3."
-triggers:
-  - "gproject-patterns-researcher: research patterns"
-  - "Dispatched by gproject-orchestrator Phase 3"
+description: >
+  Researches best practices per technology in the chosen stack and defines
+  application architecture patterns. Produces constraints that PRD must follow.
+  Use when: dispatched by gproject-orchestrator Phase 3.
+  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-patterns-researcher
 
 ## Purpose
@@ -31,3 +28,212 @@ and architectural decisions for each technology. The output becomes a set of
 | 4 | NEVER copy-paste generic "best practices" — every recommendation must be contextualized to THIS project |
 | 5 | Output MUST be structured as checkable constraints, not prose advice |
 | 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Research per-technology patterns and define application architecture"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/stack-decision.md
+  - .metaproject/jobs/<job>/artifacts/problem-statement.md
+decisions_so_far:
+  D_level: "..."
+  D_frontend: "..."
+  D_backend: "..."
+  D_database: "..."
+  D_deploy: "..."
+  # All stack decisions
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: architecture pattern, key per-tech decisions, constraint count>"
+new_decisions:
+  D_arch_pattern: "<e.g., Clean Architecture, Feature-Sliced, MVC>"
+  D_api_style: "<REST | GraphQL | tRPC | gRPC>"
+  D_state_management: "<approach>"
+  D_auth_pattern: "<JWT | session | OAuth flow>"
+  D_testing_strategy: "<unit + integration + e2e split>"
+  D_error_handling: "<pattern>"
+  D_logging_observability: "<approach>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/architecture.md"
+additional_artifacts:
+  - ".metaproject/jobs/<job>/artifacts/tech-bestpractices.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Define Application Architecture
+
+Based on project level and stack, select architecture pattern:
+
+| Level | Typical Pattern | Why |
+|-------|---------------|-----|
+| MVP | Simple layered (routes → services → DB) | Minimum indirection, fast to build |
+| Pet | Feature-based modules | Good learning structure |
+| Startup | Clean Architecture / Hexagonal | Testable, scalable when team grows |
+| Production | DDD + CQRS where justified | Complex domain needs it |
+
+Document the pattern with:
+- Layer diagram (which layers, what goes where)
+- Dependency direction (who imports whom)
+- Module/feature structure (how to organize code)
+- Cross-cutting concerns (logging, auth, error handling)
+
+### Step 2: Per-Technology Research
+
+For EACH technology in the stack, research and document:
+
+#### Frontend (e.g., Next.js)
+- Project structure pattern (App Router conventions, feature folders)
+- Component patterns (Server vs Client components, composition)
+- State management pattern (chosen approach + why)
+- Data fetching pattern (Server Actions, SWR, React Query)
+- Styling approach (Tailwind, CSS Modules, styled-components)
+- Form handling pattern
+- Error boundary strategy
+- Testing approach (unit: Vitest, e2e: Playwright)
+
+#### Backend (e.g., NestJS)
+- Module structure pattern
+- DTO and validation approach
+- Service layer patterns
+- Repository / data access pattern
+- Error handling (exception filters, typed errors)
+- Authentication and authorization pattern
+- API versioning strategy
+- Testing approach (unit + integration)
+
+#### Database (e.g., PostgreSQL)
+- Schema design approach (normalized vs denormalized for use case)
+- Migration strategy and tooling
+- Indexing guidelines for expected queries
+- Connection pooling approach
+- Backup and recovery (if production level)
+
+#### Infrastructure (e.g., Docker)
+- Container structure (multi-stage builds, compose setup)
+- Environment management (dev/staging/prod)
+- CI/CD pipeline pattern
+- Monitoring and logging stack
+
+### Step 3: Define API Contract Style
+
+Based on project needs:
+- REST: resource-based, OpenAPI spec, versioning scheme
+- GraphQL: schema-first vs code-first, resolver patterns
+- tRPC: shared types, router structure
+- gRPC: proto file organization, service boundaries
+
+### Step 4: Cross-Cutting Patterns
+
+Define patterns that span all layers:
+- **Authentication flow**: complete auth pattern (signup, login, token refresh, logout)
+- **Authorization**: RBAC, ABAC, or simple role checks
+- **Error handling**: typed errors, error codes, user-facing messages
+- **Logging**: structured logging format, log levels, sensitive data masking
+- **Validation**: where validation happens (API layer, domain layer, both)
+- **Testing**: test pyramid ratios for this project level
+
+### Step 5: Write Architecture Doc
+
+Write `artifacts/architecture.md`:
+
+```markdown
+# Architecture: <Project/Task Name>
+
+## Architecture Pattern: <Pattern Name>
+**Rationale**: <why this pattern for this project>
+**Alternative considered**: <pattern and why rejected>
+
+## Layer Diagram
+<describe layers and dependencies>
+
+## Module Structure
+<how code is organized — by feature, by layer, hybrid>
+
+## Component Interaction
+<how layers communicate — direct calls, events, DTOs>
+
+## Cross-Cutting Concerns
+### Authentication: <pattern>
+### Error Handling: <pattern>
+### Logging: <pattern>
+### Validation: <pattern>
+
+## Key Architecture Decisions
+| Decision | Choice | Rationale | Alternative |
+|----------|--------|-----------|-------------|
+| <decision> | <choice> | <why> | <what else> |
+```
+
+### Step 6: Write Best Practices Constraints
+
+Write `artifacts/tech-bestpractices.md` — this is the **constraint document**
+that PRD writer must follow:
+
+```markdown
+# Technical Best Practices & Constraints
+
+## How to Use This Document
+Every requirement in the PRD MUST be compatible with these constraints.
+The consistency-checker (Phase 5) validates PRD against these rules.
+
+## Frontend Constraints (<technology>)
+### MUST
+- [ ] <constraint 1 — e.g., "Use Server Components by default, Client only when needed">
+- [ ] <constraint 2>
+### MUST NOT
+- [ ] <antipattern 1 — e.g., "Do not use getServerSideProps in App Router">
+- [ ] <antipattern 2>
+### SHOULD
+- [ ] <recommendation 1>
+
+## Backend Constraints (<technology>)
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+### SHOULD
+- [ ] ...
+
+## Database Constraints (<technology>)
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+
+## API Constraints
+### MUST
+- [ ] ...
+
+## Infrastructure Constraints
+### MUST
+- [ ] ...
+
+## Testing Constraints
+### MUST
+- [ ] <e.g., "Every API endpoint must have integration test">
+- [ ] <e.g., "Critical user flows must have e2e tests">
+### Test Pyramid Target
+- Unit: <X>%
+- Integration: <Y>%
+- E2E: <Z>%
+
+## Security Constraints
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+```
+
+### Step 7: Return Summary
+
+Compact summary: architecture pattern, number of constraints defined,
+key per-tech decisions, any concerns about pattern compatibility.

package/src/gdskills/bundled/skills/planning/patterns-researcher/SKILL.cursor.md

@@ -1,18 +1,15 @@
 ---
 name: gproject-patterns-researcher
-description: "Researches per-technology best practices and defines architecture patterns that become binding PRD constraints. Use when: dispatched by gproject-orchestrator Phase 3."
-triggers:
-  - "gproject-patterns-researcher: research patterns"
-  - "Dispatched by gproject-orchestrator Phase 3"
+description: >
+  Researches best practices per technology in the chosen stack and defines
+  application architecture patterns. Produces constraints that PRD must follow.
+  Use when: dispatched by gproject-orchestrator Phase 3.
+  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-patterns-researcher
 
 ## Purpose
@@ -31,3 +28,212 @@ and architectural decisions for each technology. The output becomes a set of
 | 4 | NEVER copy-paste generic "best practices" — every recommendation must be contextualized to THIS project |
 | 5 | Output MUST be structured as checkable constraints, not prose advice |
 | 6 | Existing project patterns (task_in_project) take precedence unless they're antipatterns |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Research per-technology patterns and define application architecture"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/stack-decision.md
+  - .metaproject/jobs/<job>/artifacts/problem-statement.md
+decisions_so_far:
+  D_level: "..."
+  D_frontend: "..."
+  D_backend: "..."
+  D_database: "..."
+  D_deploy: "..."
+  # All stack decisions
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: architecture pattern, key per-tech decisions, constraint count>"
+new_decisions:
+  D_arch_pattern: "<e.g., Clean Architecture, Feature-Sliced, MVC>"
+  D_api_style: "<REST | GraphQL | tRPC | gRPC>"
+  D_state_management: "<approach>"
+  D_auth_pattern: "<JWT | session | OAuth flow>"
+  D_testing_strategy: "<unit + integration + e2e split>"
+  D_error_handling: "<pattern>"
+  D_logging_observability: "<approach>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/architecture.md"
+additional_artifacts:
+  - ".metaproject/jobs/<job>/artifacts/tech-bestpractices.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Define Application Architecture
+
+Based on project level and stack, select architecture pattern:
+
+| Level | Typical Pattern | Why |
+|-------|---------------|-----|
+| MVP | Simple layered (routes → services → DB) | Minimum indirection, fast to build |
+| Pet | Feature-based modules | Good learning structure |
+| Startup | Clean Architecture / Hexagonal | Testable, scalable when team grows |
+| Production | DDD + CQRS where justified | Complex domain needs it |
+
+Document the pattern with:
+- Layer diagram (which layers, what goes where)
+- Dependency direction (who imports whom)
+- Module/feature structure (how to organize code)
+- Cross-cutting concerns (logging, auth, error handling)
+
+### Step 2: Per-Technology Research
+
+For EACH technology in the stack, research and document:
+
+#### Frontend (e.g., Next.js)
+- Project structure pattern (App Router conventions, feature folders)
+- Component patterns (Server vs Client components, composition)
+- State management pattern (chosen approach + why)
+- Data fetching pattern (Server Actions, SWR, React Query)
+- Styling approach (Tailwind, CSS Modules, styled-components)
+- Form handling pattern
+- Error boundary strategy
+- Testing approach (unit: Vitest, e2e: Playwright)
+
+#### Backend (e.g., NestJS)
+- Module structure pattern
+- DTO and validation approach
+- Service layer patterns
+- Repository / data access pattern
+- Error handling (exception filters, typed errors)
+- Authentication and authorization pattern
+- API versioning strategy
+- Testing approach (unit + integration)
+
+#### Database (e.g., PostgreSQL)
+- Schema design approach (normalized vs denormalized for use case)
+- Migration strategy and tooling
+- Indexing guidelines for expected queries
+- Connection pooling approach
+- Backup and recovery (if production level)
+
+#### Infrastructure (e.g., Docker)
+- Container structure (multi-stage builds, compose setup)
+- Environment management (dev/staging/prod)
+- CI/CD pipeline pattern
+- Monitoring and logging stack
+
+### Step 3: Define API Contract Style
+
+Based on project needs:
+- REST: resource-based, OpenAPI spec, versioning scheme
+- GraphQL: schema-first vs code-first, resolver patterns
+- tRPC: shared types, router structure
+- gRPC: proto file organization, service boundaries
+
+### Step 4: Cross-Cutting Patterns
+
+Define patterns that span all layers:
+- **Authentication flow**: complete auth pattern (signup, login, token refresh, logout)
+- **Authorization**: RBAC, ABAC, or simple role checks
+- **Error handling**: typed errors, error codes, user-facing messages
+- **Logging**: structured logging format, log levels, sensitive data masking
+- **Validation**: where validation happens (API layer, domain layer, both)
+- **Testing**: test pyramid ratios for this project level
+
+### Step 5: Write Architecture Doc
+
+Write `artifacts/architecture.md`:
+
+```markdown
+# Architecture: <Project/Task Name>
+
+## Architecture Pattern: <Pattern Name>
+**Rationale**: <why this pattern for this project>
+**Alternative considered**: <pattern and why rejected>
+
+## Layer Diagram
+<describe layers and dependencies>
+
+## Module Structure
+<how code is organized — by feature, by layer, hybrid>
+
+## Component Interaction
+<how layers communicate — direct calls, events, DTOs>
+
+## Cross-Cutting Concerns
+### Authentication: <pattern>
+### Error Handling: <pattern>
+### Logging: <pattern>
+### Validation: <pattern>
+
+## Key Architecture Decisions
+| Decision | Choice | Rationale | Alternative |
+|----------|--------|-----------|-------------|
+| <decision> | <choice> | <why> | <what else> |
+```
+
+### Step 6: Write Best Practices Constraints
+
+Write `artifacts/tech-bestpractices.md` — this is the **constraint document**
+that PRD writer must follow:
+
+```markdown
+# Technical Best Practices & Constraints
+
+## How to Use This Document
+Every requirement in the PRD MUST be compatible with these constraints.
+The consistency-checker (Phase 5) validates PRD against these rules.
+
+## Frontend Constraints (<technology>)
+### MUST
+- [ ] <constraint 1 — e.g., "Use Server Components by default, Client only when needed">
+- [ ] <constraint 2>
+### MUST NOT
+- [ ] <antipattern 1 — e.g., "Do not use getServerSideProps in App Router">
+- [ ] <antipattern 2>
+### SHOULD
+- [ ] <recommendation 1>
+
+## Backend Constraints (<technology>)
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+### SHOULD
+- [ ] ...
+
+## Database Constraints (<technology>)
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+
+## API Constraints
+### MUST
+- [ ] ...
+
+## Infrastructure Constraints
+### MUST
+- [ ] ...
+
+## Testing Constraints
+### MUST
+- [ ] <e.g., "Every API endpoint must have integration test">
+- [ ] <e.g., "Critical user flows must have e2e tests">
+### Test Pyramid Target
+- Unit: <X>%
+- Integration: <Y>%
+- E2E: <Z>%
+
+## Security Constraints
+### MUST
+- [ ] ...
+### MUST NOT
+- [ ] ...
+```
+
+### Step 7: Return Summary
+
+Compact summary: architecture pattern, number of constraints defined,
+key per-tech decisions, any concerns about pattern compatibility.

package/src/gdskills/bundled/skills/planning/planner/SKILL.codex.md

@@ -1,18 +1,14 @@
 ---
 name: gproject-planner
-description: "Generates roadmap, milestones, task breakdown with dependency graph and effort estimates from approved PRD. Use when: dispatched by gproject-orchestrator Phase 6."
-triggers:
-  - "gproject-planner: generate roadmap"
-  - "Dispatched by gproject-orchestrator Phase 6"
+description: >
+  Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
+  Use when: dispatched by gproject-orchestrator Phase 6.
+  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-planner
 
 ## Purpose
@@ -31,3 +27,166 @@ to feed into job-orchestrator or task-implementer.
 | 4 | P0 user stories MUST be in Milestone 1 |
 | 5 | Each milestone MUST be independently deployable / demonstrable |
 | 6 | Infrastructure and setup tasks come before feature tasks |
+
+---
+
+## Input Contract
+
+```yaml
+task: "Generate roadmap and task breakdown"
+input_artifacts:
+  - .metaproject/jobs/<job>/artifacts/prd.md
+  - .metaproject/jobs/<job>/artifacts/architecture.md
+decisions_so_far:
+  D_level: "..."
+  D_frontend: "..."
+  D_backend: "..."
+  # All relevant decisions
+```
+
+## Output Contract
+
+```yaml
+status: "DONE" | "NEEDS_CONTEXT"
+summary: "<3-5 sentences: milestone count, total tasks, critical path duration>"
+new_decisions:
+  D_milestones: ["<M1 name>", "<M2 name>", ...]
+  D_estimated_duration: "<range>"
+  D_critical_path: "<list of blocking tasks>"
+artifact_path: ".metaproject/jobs/<job>/artifacts/roadmap.md"
+```
+
+---
+
+## Workflow
+
+### Step 1: Decompose User Stories into Tasks
+
+For each user story, break into implementation tasks:
+
+```yaml
+- task_id: "T-001"
+  title: "<specific task>"
+  user_story: "US-001"
+  layer: "frontend | backend | database | infra | testing"
+  type: "setup | feature | integration | test | docs"
+  estimate:
+    optimistic: "<time>"
+    realistic: "<time>"
+    pessimistic: "<time>"
+  depends_on: ["T-000"]  # or [] if no deps
+  acceptance_criteria:
+    - "<from user story, scoped to this task>"
+  files_likely_affected:
+    - "<file path or module>"
+```
+
+### Step 2: Identify Dependencies
+
+Build dependency graph:
+- Infrastructure tasks → before all feature tasks
+- Database schema → before backend → before frontend
+- Auth setup → before any authenticated feature
+- Shared components → before pages that use them
+
+Verify: no cycles in dependency graph.
+
+### Step 3: Group into Milestones
+
+Each milestone:
+- Has a clear deliverable (demo-able, deployable)
+- Contains all P0 stories it covers (no half-done P0 at milestone end)
+- Ends with a verification checkpoint
+
+Typical milestone structure:
+
+**M0: Foundation**
+- Project setup, tooling, CI/CD, dev environment
+- Database schema initial migration
+- Auth skeleton
+- Deploy pipeline to staging
+
+**M1: Core (P0 features)**
+- All P0 user stories
+- Core API endpoints
+- Core UI flows
+- Integration tests for critical paths
+
+**M2: Complete (P1 features)**
+- P1 user stories
+- Polish, edge cases
+- Performance optimization
+- Full test coverage
+
+**M3: Launch-Ready (if production level)**
+- P2 features (selected)
+- Security hardening
+- Monitoring, alerting
+- Documentation
+- Load testing
+
+### Step 4: Estimate Critical Path
+
+Identify the longest dependency chain and estimate total duration.
+Flag tasks that block the most other tasks.
+
+### Step 5: Write Roadmap
+
+Write `artifacts/roadmap.md`:
+
+```markdown
+# Roadmap: <Project/Task Name>
+
+## Overview
+- **Milestones**: <count>
+- **Total tasks**: <count>
+- **Estimated duration**: <optimistic> — <realistic> — <pessimistic>
+- **Critical path**: <list of blocking tasks>
+
+## Milestone 0: Foundation
+**Deliverable**: <what can be demonstrated>
+**Duration estimate**: <range>
+
+### Tasks
+| ID | Title | Layer | Depends On | Estimate | Story |
+|----|-------|-------|-----------|----------|-------|
+| T-001 | <title> | infra | — | <range> | — |
+| T-002 | <title> | database | T-001 | <range> | — |
+
+## Milestone 1: Core
+**Deliverable**: <what can be demonstrated>
+**Duration estimate**: <range>
+
+### Tasks
+| ID | Title | Layer | Depends On | Estimate | Story |
+|----|-------|-------|-----------|----------|-------|
+| T-010 | <title> | backend | T-002 | <range> | US-001 |
+
+## ...
+
+## Dependency Graph (summary)
+<textual description of key dependency chains>
+T-001 → T-002 → T-010 → T-015 (critical path)
+T-001 → T-003 → T-011 (parallel track)
+
+## Risk-Adjusted Timeline
+| Scenario | Duration | Assumptions |
+|----------|---------|-------------|
+| Optimistic | <time> | No blockers, all estimates hold |
+| Realistic | <time> | Normal friction, 1-2 minor blockers |
+| Pessimistic | <time> | Major unknowns surface, rework needed |
+
+## Parallelization Opportunities
+<Which tasks can run simultaneously — useful for team or multi-agent execution>
+
+## Integration with job-orchestrator
+<How to feed this roadmap into job-orchestrator for automated implementation>
+- Each milestone maps to a job-orchestrator run
+- Tasks within a milestone map to issue-analyzer output format
+- Dependency order maps to wave-based execution
+```
+
+### Step 6: Return Summary
+
+Compact summary: milestone count, task count, critical path duration,
+biggest scheduling risk.