**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.

# Gproject Spec Writer > 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. - Skill: `mrciphersmith/gproject-spec-writer` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add mrciphersmith/gproject-spec-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/mrciphersmith/gproject-spec-writer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: MrCipherSmith (https://skillmd.com/u/mrciphersmith) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mrciphersmith/gproject-spec-writer --- # 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 | --- ## Input Contract ```yaml task: "Generate PRD / Implementation Plan" mode: "new_project" | "task_in_project" input_artifacts: - jobs//artifacts/problem-statement.md - jobs//artifacts/architecture.md - jobs//artifacts/tech-bestpractices.md - jobs//decisions.md decisions_so_far: ``` ## 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: [""] artifact_path: "jobs//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-: **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.