vt-c-pd-pid¶
Create or update a Project Implementation Document (PID) with technical architecture decisions, stack selection, and implementation constraints. Invokes specialized sub-agents for architecture, database, API, and security analysis.
Plugin: core-standards
Category: Product Design Workflow
Command: /vt-c-pd-pid
Product Design: PID Creation¶
Create comprehensive Project Implementation Documents (PIDs) that capture technical architecture decisions, technology stack selection, and implementation constraints. The PID serves as the technical companion to the PRD, informing requirements feasibility and providing the foundation for specs generation.
Workflow Position¶
/vt-c-pd-0-start → /vt-c-pd-1-research → /vt-c-pd-pid → /vt-c-pd-2-prd → /vt-c-pd-3-prototype → /vt-c-pd-4-validate → /vt-c-pd-6-handoff → /vt-c-activate
│
└── You are here
Output: 03-PRD/PID.md
Invocation¶
/vt-c-pd-pid # Interactive PID creation
/vt-c-pd-pid --update # Update existing PID with new constraints
/vt-c-pd-pid --review # Review PID completeness before pd-2-prd
Configuration¶
# Project paths
output_path: "03-PRD/PID.md"
product_vision: "PRODUCT-VISION.md"
research_path: "02-Knowledge/"
personas_path: "02-Knowledge/02-Zielgruppen-Personas/"
prd_path: "03-PRD/PRD.md"
Sub-Agent Architecture¶
This skill invokes specialized agents sequentially, each building on prior results, with a holistic security review of the assembled PID:
┌─────────────────────────────────────────────────────────────────┐
│ PID Generation Pipeline │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 2: Requirements Discovery (Interactive) │
│ │ User answers about app type, scale, constraints │
│ ▼ │
│ Step 3a: best-practices-researcher │
│ │ Research stack options, compare frameworks │
│ │ Output: Stack recommendation │
│ ▼ │
│ Step 3b: architecture-strategist │
│ │ Design system architecture, component boundaries │
│ │ Output: Architecture diagram + patterns │
│ ▼ │
│ Step 3c: data-integrity-guardian │
│ │ Database design, schema approach, migration strategy │
│ │ Output: Data layer specification │
│ ▼ │
│ Step 3d: api-design-reviewer │
│ │ API style, endpoint structure, conventions │
│ │ Output: API specification │
│ ▼ │
│ Step 3e: security-sentinel │
│ │ Auth architecture, data protection, compliance │
│ │ Output: Security specification │
│ ▼ │
│ Step 4: Assemble PID Document │
│ │ Combine all agent outputs into PID template │
│ ▼ │
│ Step 4b: security-sentinel (REVIEW mode) │
│ │ Audit complete PID for cross-section security issues │
│ │ Cross-reference with PRD if available │
│ │ Output: Security findings + auto-fix critical issues │
│ ▼ │
│ Step 5: Review with User (includes security findings) │
│ │
└─────────────────────────────────────────────────────────────────┘
Iteration Loop Integration¶
Step 0: Check Design State (Before Starting)¶
Before beginning PID work, check the design state:
# Load design state
Read: .design-state.yaml
# Check for pending inbox items
if inbox.pending_items exists:
Run: /vt-c-pd-inbox-scan to process first
If this is an iteration (returning to PID):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Iteration Context: pd-pid
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Returning to PID phase (Iteration {n})
Trigger: {trigger from state file}
Reason: {reason from state file}
Previous PID version: {artifacts.pid.version}
Focus: Update technical decisions based on new constraints
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quality Gate: pd-pid¶
Mark phase as complete when: - [ ] Technology stack defined with versions - [ ] System architecture documented with diagram - [ ] Database approach selected and key entities identified - [ ] API conventions specified - [ ] Security requirements assessed - [ ] Holistic security review passed (no critical findings)
Update state file on completion:
quality_gates:
pd-pid:
passed: true
passed_at: "{timestamp}"
criteria:
tech_stack_defined: true
architecture_documented: true
database_designed: true
api_specified: true
security_assessed: true
security_review_passed: true
artifacts:
pid:
version: "{increment}"
path: "03-PRD/PID.md"
status: "complete"
Execution Instructions¶
Step 1: Gather Project Context¶
- Read existing project inputs:
PRODUCT-VISION.md-- product goals, target audience, key differentiators02-Knowledge/02-Zielgruppen-Personas/-- user personas (if pd-1-research completed)02-Knowledge/04-Dokumente/-- research findings, interview analyses03-PRD/PRD.md-- if exists (for--updatemode)-
03-PRD/PID.md-- if exists (for--updatemode) -
Display context:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PID Creation - Product Design: Technical Architecture ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Project: [directory name] Output: 03-PRD/PID.md Project Inputs: [✓/✗] PRODUCT-VISION.md [✓/✗] User personas from /vt-c-pd-1-research [✓/✗] Research findings [✓/✗] Existing PRD (for update) [✓/✗] Existing PID (for update) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: Requirements Discovery (Interactive)¶
Use AskUserQuestion to gather technical context. Ask questions in groups, adapting based on prior answers. Skip questions that are already answered by existing documents.
2a. Application Type & Scope¶
AskUserQuestion:
question: "What type of application is this?"
options:
- "Web application (SPA/SSR)"
- "Web application with mobile (responsive or PWA)"
- "Full-stack with native mobile apps"
- "API/Backend service only"
Follow-up based on answer:
AskUserQuestion:
question: "Does the application need real-time capabilities?"
options:
- "Yes - live updates, collaboration, or chat (WebSocket/SSE)"
- "Yes - notifications only (push/polling)"
- "No - standard request/response is sufficient"
AskUserQuestion:
question: "Does it need offline capability?"
options:
- "Yes - must work without internet (PWA/local storage)"
- "Partial - graceful degradation when offline"
- "No - always-online is acceptable"
2b. Scale & Performance¶
AskUserQuestion:
question: "What is the expected scale?"
options:
- "Small - under 100 concurrent users, single region"
- "Medium - 100-1000 concurrent users, single region"
- "Large - 1000+ concurrent users, multi-region"
- "Unknown - need to design for growth"
AskUserQuestion:
question: "What are the data volume expectations?"
options:
- "Light - mostly CRUD, small datasets"
- "Medium - significant data, some analytics"
- "Heavy - large datasets, file uploads, media processing"
- "Unknown at this stage"
2c. Integration & Constraints¶
AskUserQuestion:
question: "What systems need to integrate?"
multiSelect: true
options:
- "Existing database or data source"
- "Third-party APIs (payment, email, maps, etc.)"
- "SSO/Identity provider (Azure AD, Okta, Auth0)"
- "None - greenfield project"
AskUserQuestion:
question: "Multi-tenancy requirements?"
options:
- "Multi-tenant - shared infrastructure, data isolation"
- "Single-tenant - one instance per customer"
- "Not applicable - internal tool"
AskUserQuestion:
question: "Compliance requirements?"
multiSelect: true
options:
- "GDPR (EU data protection)"
- "SOC2 / ISO 27001"
- "Industry-specific (HIPAA, PCI-DSS, etc.)"
- "None specific at this stage"
2d. Team & Infrastructure¶
AskUserQuestion:
question: "What is the team's primary expertise?"
options:
- "TypeScript/JavaScript full-stack"
- "Python backend + JS frontend"
- "Java/Kotlin backend + JS frontend"
- "Mixed or flexible"
AskUserQuestion:
question: "Preferred deployment approach?"
options:
- "Containers (Docker/Kubernetes)"
- "Serverless (AWS Lambda, Vercel, Cloudflare Workers)"
- "PaaS (Railway, Render, Heroku)"
- "No preference - recommend based on project needs"
AskUserQuestion:
question: "Preferred cloud provider?"
options:
- "AWS"
- "Azure"
- "Google Cloud"
- "No preference or self-hosted"
Step 3: Invoke Sub-Agents for Deep Analysis¶
Based on the gathered requirements, invoke specialized agents sequentially. Pass all prior context (product vision, research findings, user answers) to each agent.
3a. Invoke best-practices-researcher agent¶
Provide context: - Application type, scale, team expertise from Step 2 - Product vision and features from Step 1
Agent tasks: 1. Research current best practices for the application type and scale 2. Evaluate 2-3 viable tech stack options considering: - Framework maturity and community size - AI-assisted development friendliness (type safety, documentation quality) - VisiTrans ecosystem fit (existing projects use Angular 21 + PrimeNG + NestJS + Prisma) - Team expertise alignment 3. Compare options with trade-offs 4. Recommend primary stack with justification
Expected output: Stack recommendation with comparison table
─────────────────────────────────────────────────────────────────
Tech Stack Research: [Application Type]
─────────────────────────────────────────────────────────────────
Option A: [Stack] (Recommended)
Pros: [list]
Cons: [list]
Fit: [why this matches the requirements]
Option B: [Stack]
Pros: [list]
Cons: [list]
Trade-off: [what you give up]
Recommendation: [Option A] because [reasoning]
─────────────────────────────────────────────────────────────────
After receiving the recommendation, use AskUserQuestion to confirm:
AskUserQuestion:
question: "Which tech stack should we proceed with?"
options:
- "[Option A] (Recommended)"
- "[Option B]"
- "[Option C] (if applicable)"
3b. Invoke architecture-strategist agent¶
Provide context: - Confirmed tech stack from Step 3a - Application type, scale, real-time needs, integration requirements - Product vision and feature set
Agent tasks: 1. Design overall system architecture 2. Define component boundaries and service topology 3. Create ASCII architecture diagram showing all layers 4. Evaluate architectural patterns: - Monolith vs microservices vs modular monolith - API style (REST vs GraphQL vs tRPC) - State management approach - Caching strategy 5. Document key architectural decisions with rationale
Expected output: Architecture section with diagram and decisions
3c. Invoke data-integrity-guardian agent¶
Provide context: - Architecture decisions from Step 3b - Confirmed tech stack (especially database choice) - Data volume expectations, multi-tenancy requirements - Key features from product vision
Agent tasks: 1. Recommend database type and justify (relational, document, graph, or polyglot) 2. Design initial entity model based on product features 3. Define key entities with attributes and relationships 4. Specify ORM/query layer approach 5. Outline migration strategy and backup approach 6. Address multi-tenancy data isolation if applicable
Expected output: Database section with entity model
3d. Invoke api-design-reviewer agent¶
Provide context: - Architecture from Step 3b (API style decision) - Entity model from Step 3c - Key features from product vision - Authentication approach
Agent tasks: 1. Define API style and conventions (URL structure, versioning, error format) 2. Design endpoint structure for key feature areas 3. Specify authentication flow and token handling 4. Define pagination, filtering, and sorting patterns 5. Specify WebSocket/real-time event patterns if applicable
Expected output: API specification section
3e. Invoke security-sentinel agent¶
Provide context: - Full architecture and stack decisions - Authentication approach from Step 3d - Compliance requirements from Step 2 - Multi-tenancy model if applicable
Agent tasks: 1. Assess security requirements for the application type 2. Design authentication/authorization architecture 3. Specify data protection measures (encryption at rest/transit, PII handling) 4. Define infrastructure security (secrets management, network policies) 5. Address compliance requirements (GDPR, SOC2, etc.) 6. Identify technical security risks
Expected output: Security section with requirements and risks
Step 4: Generate PID Document¶
Assemble all agent outputs into the PID document at 03-PRD/PID.md.
Use the PID template structure. Fill each section from agent outputs:
| PID Section | Source |
|---|---|
| 1.1 System Architecture | architecture-strategist (Step 3b) |
| 1.2 Technology Stack | best-practices-researcher (Step 3a) + user confirmation |
| 1.3 Development Infrastructure | User answers (Step 2d) + architecture-strategist |
| 2. API Specification | api-design-reviewer (Step 3d) |
| 3. Database Schema | data-integrity-guardian (Step 3c) |
| 4. Security & Compliance | security-sentinel (Step 3e) |
| 5. Deployment & Infrastructure | User answers (Step 2d) + architecture-strategist |
| 6. Technical Risks | Aggregated from all agents |
| 7. Quality Assurance | Derived from architecture + security |
Step 4b: Security Review of Assembled PID¶
After assembling the complete PID, invoke security-sentinel agent a second time -- now in review mode to audit the entire document holistically. This is distinct from Step 3e which generates the Security section; Step 4b reviews ALL sections for cross-cutting security implications.
Provide context:
- The complete assembled PID document (all sections from Step 4)
- 03-PRD/PRD.md if it exists (to cross-reference product requirements)
- PRODUCT-VISION.md for business context
- Compliance requirements from Step 2
Agent tasks: 1. Review the architecture (PID Section 1) for security implications: - Are component boundaries properly isolated? - Is the network topology secure (API gateway, firewall, WAF)? - Are there single points of failure that could be exploited? 2. Review the database schema (PID Section 3) for data protection: - Is PII properly identified and flagged for encryption? - Are access controls defined at the data layer? - Is tenant isolation enforced in multi-tenant designs? 3. Review the API specification (PID Section 2) for attack surface: - Are all endpoints authenticated and authorized? - Is input validation specified for each endpoint? - Are rate limiting and abuse prevention in place? - Are sensitive data fields excluded from list/search responses? 4. Review the deployment (PID Section 5) for infrastructure security: - Are secrets management practices adequate? - Is the CI/CD pipeline secure (no credentials in logs)? - Are container images scanned and signed? 5. Cross-reference with PRD (if exists): - Do PRD user stories imply data access patterns that need authorization? - Are there PRD features with elevated security risk (payments, file uploads, user data export)? 6. Produce a Security Review Summary with: - Findings categorized as Critical / Major / Minor - Specific PID section references for each finding - Recommended mitigations
Expected output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Security Review - PID Audit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reviewed: PID.md (all sections) + PRD.md (if available)
Findings:
─────────────────────────────────────────────────────────────────
Critical: [N]
Major: [N]
Minor: [N]
[For each finding:]
[SEVERITY] [PID Section] - [Issue]
Risk: [what could go wrong]
Recommendation: [specific fix]
Overall Assessment:
[✓] PID security posture is adequate
[✗] PID requires security improvements before proceeding
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If Critical findings exist: Automatically update the relevant PID sections with the security-sentinel's recommendations before presenting to the user. Flag the changes in the Step 5 review summary.
If only Major/Minor findings: Include them in the Step 5 review summary for user awareness, but don't block.
Step 5: Review and Validate¶
Present PID summary to user (including security review results):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PID Generated - Review Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: [name]
Architecture: [pattern] ([brief description])
Technology Stack:
─────────────────────────────────────────────────────────────────
• Frontend: [framework + key libraries]
• Backend: [framework + key libraries]
• Database: [type + ORM]
• Auth: [method]
• Deployment: [approach]
Key Architecture Decisions:
─────────────────────────────────────────────────────────────────
1. [Decision 1] - [rationale]
2. [Decision 2] - [rationale]
3. [Decision 3] - [rationale]
Technical Risks:
─────────────────────────────────────────────────────────────────
• [Risk 1] - Mitigation: [approach]
• [Risk 2] - Mitigation: [approach]
Security Review (Step 4b):
─────────────────────────────────────────────────────────────────
• Findings: [N critical, N major, N minor]
• [If critical were found and auto-fixed]: Critical issues resolved in PID
• [Top findings summary]
Open Questions: [N items needing further input]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use AskUserQuestion:
AskUserQuestion:
question: "How would you like to proceed with the PID?"
options:
- "Approve and save (Recommended)"
- "Adjust specific sections"
- "Restart with different stack"
Step 6: Update Design State¶
After writing PID.md, update .design-state.yaml:
quality_gates:
pd-pid:
passed: true
passed_at: "{timestamp}"
criteria:
tech_stack_defined: true
architecture_documented: true
database_designed: true
api_specified: true
security_assessed: true
security_review_passed: true
artifacts:
pid:
version: "1.0"
path: "03-PRD/PID.md"
status: "complete"
Step 7: Summary and Next Steps¶
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PID Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Location: 03-PRD/PID.md
Version: 1.0
Sub-Agents Consulted:
─────────────────────────────────────────────────────────────────
✓ best-practices-researcher - Stack selection
✓ architecture-strategist - System design
✓ data-integrity-guardian - Database design
✓ api-design-reviewer - API conventions
✓ security-sentinel - Security assessment (Section 4)
✓ security-sentinel - PID security review (cross-section audit)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Run: /vt-c-pd-2-prd
Creates PRD informed by PID technical constraints
2. Run: /vt-c-pd-pid --update
Update PID if requirements change during PRD creation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Mode: Update (--update)¶
When invoked with --update:
- Read existing
03-PRD/PID.md - Read
03-PRD/PRD-DELTA.mdfor any technical constraint changes - Ask user what needs updating
- Invoke only the relevant sub-agents for the changed sections
- Update PID.md in place, increment version
- Update design state
Mode: Review (--review)¶
When invoked with --review:
- Read existing
03-PRD/PID.md - Check completeness against quality gate criteria
- Report missing or incomplete sections
- Suggest running specific sub-agents to fill gaps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PID Completeness Review
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[✓] Technology stack defined with versions
[✓] System architecture documented with diagram
[✗] Database schema incomplete - missing entity relationships
[✓] API conventions specified
[✗] Security assessment missing compliance section
Recommendation: Run /vt-c-pd-pid --update to address gaps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Integration with Product Design Workflow¶
/vt-c-pd-1-research ← Provides user context and personas
│
▼
/vt-c-pd-pid ← YOU ARE HERE - Technical architecture
│
▼
/vt-c-pd-2-prd ← PRD informed by PID constraints
Integration with Design Agents¶
The PID can be reviewed using design agents:
architecture-strategist- Review architecture decisionsperformance-oracle- Validate performance assumptionssecurity-sentinel- Audit security approach
Quality Checklist¶
- [ ] Technology stack defined with specific versions
- [ ] System architecture diagram present
- [ ] Architectural decisions documented with rationale
- [ ] Database type selected and key entities defined
- [ ] API conventions and key endpoints specified
- [ ] Authentication/authorization approach defined
- [ ] Security and compliance requirements addressed
- [ ] Deployment strategy documented
- [ ] Technical risks identified with mitigations
- [ ] Security review of complete PID passed (no critical findings)
- [ ] Cross-section security implications addressed
- [ ] PID version and document history maintained