feat: Platform Requirements → Build Specification
Transforms the Platform Requirements steps from a technology shopping list into a complete build specification that a coding agent can execute autonomously. New steps: - 28a: Data Model — complete database schema (every table, column, type, default, constraint, relationship, index, release phase tags) - 28b: State Machines — every stateful entity gets states, transitions, triggers, per-phase action differences, feature gate pattern - 28c: Business Logic, Events & API — calculations as pseudocode, event system (scheduled/webhook/user), notification rules, complete API surface with request/response shapes, auth spec, AI integration Updated steps: - 28: Tech Stack now includes architecture pattern and API style - 32: Finalization now includes the Litmus Test — "Can a coding agent build the entire platform from this document alone?" Inspired by RightsTrak session where Saga produced a tech selection document and Mårten had to push four times to get a build spec. The 200-line tech list became a 700-line actionable specification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mårten Angner
parent
490504e632
commit
c66c99ea18
|
|
@ -1,17 +1,17 @@
|
|||
---
|
||||
name: 'step-28-tech-stack'
|
||||
description: 'Capture core technology decisions'
|
||||
description: 'Capture core technology decisions and architecture approach'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-29-integrations.md'
|
||||
nextStepFile: './step-28a-data-model.md'
|
||||
workflowFile: '../workflow.md'
|
||||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
||||
# Step 28: Technology Stack
|
||||
# Step 28: Technology Stack & Architecture
|
||||
|
||||
## STEP GOAL:
|
||||
Capture core technology decisions for the project including CMS/framework, frontend, styling, and hosting.
|
||||
Capture core technology decisions — frontend, backend, database, hosting, and the overall architectural approach. This is the foundation that all subsequent build specification steps build on.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
|
|
@ -23,86 +23,92 @@ Capture core technology decisions for the project including CMS/framework, front
|
|||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
- You are a Strategic Business Analyst guiding technology choices with clear trade-off explanations
|
||||
- You are a Strategic Business Analyst and Systems Architect guiding technology choices with clear trade-off explanations
|
||||
- If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- We engage in collaborative dialogue, not command-response
|
||||
- You bring structured thinking and facilitation skills, user brings domain expertise and product vision
|
||||
- Maintain collaborative and strategic tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
- Focus: CMS/Framework, frontend tech, styling approach, hosting decisions
|
||||
- Focus: Frontend framework, backend language, database, hosting, architecture pattern
|
||||
- FORBIDDEN: Do not recommend technology without explaining trade-offs at user's technical level
|
||||
- Approach: Present options with trade-offs, explain at appropriate level, document rationale
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
- Primary goal: Technology stack documented with rationale
|
||||
- Save/document outputs appropriately
|
||||
- Avoid generating content without user input
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
- Available context: Product Brief, platform initialization, user's technical level
|
||||
- Focus: Core technology choices
|
||||
- Limits: Strategic technology direction, not detailed implementation
|
||||
- Dependencies: Step 27 completed
|
||||
- For app-type products: always ask about API architecture (REST vs GraphQL vs RPC)
|
||||
- For web-only: simpler choices, static vs dynamic, CMS vs custom
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. CMS/Framework Selection
|
||||
### 0. Check Material Analysis Status
|
||||
|
||||
If not already decided, ask:
|
||||
- "What type of site are we building?" (reference Product Brief)
|
||||
- Present options appropriate to project:
|
||||
- **WordPress** - Content-focused, client can update, huge ecosystem
|
||||
- **Next.js/React** - Dynamic, app-like, developer-maintained
|
||||
- **Static (HTML/11ty)** - Simple, fast, minimal maintenance
|
||||
- **Other** - Based on specific requirements
|
||||
**If technology stack was already confirmed during the Material Analysis Phase (Step 1):**
|
||||
Run in **Confirmation Mode** — do NOT re-run the full exploratory conversation:
|
||||
1. Reference the confirmed stack: "We confirmed your technology stack as [synthesis from analysis phase]."
|
||||
2. Ask: "Anything to add or refine before I document it?"
|
||||
3. If nothing: synthesize, document, and advance
|
||||
4. If additions: capture them, update the synthesis, confirm, then advance
|
||||
|
||||
### 2. Theme/Styling Approach
|
||||
**If no materials exist or tech stack was not covered in materials:**
|
||||
Run the full exploration below.
|
||||
|
||||
For WordPress:
|
||||
- **Block Theme (Gutenberg)** - Modern, visual editing, limited flexibility
|
||||
- **Classic Theme + Tailwind** - Developer control, Tailwind utility classes
|
||||
- **Classic Theme + Custom CSS** - Full control, more maintenance
|
||||
- **Existing Theme** - Faster start, less unique
|
||||
### 1. Architecture Pattern
|
||||
|
||||
For React/Next:
|
||||
- **Tailwind CSS** - Utility-first, rapid development
|
||||
- **CSS Modules** - Component-scoped styles
|
||||
- **Styled Components** - CSS-in-JS approach
|
||||
Based on the Product Brief, determine what we're building:
|
||||
- **Static site** — Marketing site, blog, portfolio (Astro, 11ty, Hugo)
|
||||
- **Server-rendered app** — Dynamic pages, SEO-critical (Next.js, Nuxt, SvelteKit)
|
||||
- **SPA + API** — Application with separate frontend and backend (React/Vue + REST/GraphQL)
|
||||
- **Cross-platform app** — Mobile + web from one codebase (Flutter, React Native)
|
||||
- **Backend service** — API-first, headless (Go, Node, Python, Rust)
|
||||
|
||||
### 3. Document Rationale
|
||||
- Why this choice fits the project
|
||||
Ask: "Based on your product concept, what kind of system are we building?"
|
||||
|
||||
### 2. Frontend Technology
|
||||
|
||||
Based on architecture pattern:
|
||||
- Framework choice and rationale
|
||||
- Styling approach (Tailwind, CSS modules, styled-components)
|
||||
- State management approach (if SPA/app)
|
||||
- Mobile considerations (responsive, PWA, native)
|
||||
|
||||
### 3. Backend Technology
|
||||
|
||||
- Language and framework (Go, Node/Express, Python/FastAPI, etc.)
|
||||
- API style (REST, GraphQL, gRPC, tRPC)
|
||||
- Authentication approach (JWT, sessions, OAuth providers)
|
||||
- Background job processing (if needed)
|
||||
|
||||
### 4. Database
|
||||
|
||||
- Primary database (PostgreSQL, MySQL, SQLite, MongoDB)
|
||||
- Caching layer (Redis, in-memory)
|
||||
- Search (built-in, Elasticsearch, Meilisearch)
|
||||
- File storage (S3, local, CDN)
|
||||
|
||||
### 5. Hosting & Deployment
|
||||
|
||||
- Where it runs (cloud provider, VPS, serverless, PaaS)
|
||||
- CI/CD approach
|
||||
- Environment strategy (dev, staging, production)
|
||||
- Domain and DNS
|
||||
|
||||
### 6. Document Rationale
|
||||
|
||||
For each choice:
|
||||
- Why this fits the project
|
||||
- Trade-offs acknowledged
|
||||
- Client maintenance implications
|
||||
- Scaling implications
|
||||
- Team skill alignment
|
||||
|
||||
### 4. Capture in Template
|
||||
- Fill in Technology Stack section of output document
|
||||
### 7. Design Log Update
|
||||
|
||||
### 5. Design Log Update
|
||||
After completing this step, update the design log:
|
||||
|
||||
```markdown
|
||||
### Step 28: Technology Stack
|
||||
**Q:** CMS/framework, styling approach, hosting?
|
||||
**A:** [User responses - summarized]
|
||||
**Documented in:** platform-requirements.md (Technology Stack section)
|
||||
**Key insights:** [Important decisions or revelations]
|
||||
**Status:** Complete
|
||||
**Timestamp:** [HH:MM]
|
||||
```
|
||||
Update design log with technology decisions and rationale.
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
Display: "**Select an Option:** [C] Continue to next step"
|
||||
Display: "**Select an Option:** [C] Continue to Data Model"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Load, read entire file, then execute {nextStepFile}
|
||||
- IF M: Return to {workflowFile} or {activityWorkflowFile}
|
||||
- IF M: Return to {workflowFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN step objectives are met and user confirms will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
|
|
@ -111,15 +117,14 @@ ONLY WHEN step objectives are met and user confirms will you then load and read
|
|||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
- CMS/framework choice documented with rationale
|
||||
- Styling approach defined
|
||||
- Trade-offs acknowledged
|
||||
- Client maintenance implications noted
|
||||
- Architecture pattern identified
|
||||
- Frontend, backend, database, hosting decisions documented
|
||||
- Rationale captured for each choice
|
||||
- User confirmed
|
||||
|
||||
### FAILURE:
|
||||
- Recommended technology without trade-off explanation
|
||||
- Used overly technical language for non-technical user
|
||||
- Skipped database or API architecture for an app-type product
|
||||
- Generated tech stack without user input
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
name: 'step-28a-data-model'
|
||||
description: 'Define the complete database schema — every table, column, type, and relationship'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-28b-state-machines.md'
|
||||
workflowFile: '../workflow.md'
|
||||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
||||
# Step 28a: Data Model
|
||||
|
||||
## STEP GOAL:
|
||||
Define the complete database schema. Every entity the system manages becomes a table. Every attribute becomes a column with a specific type. Every relationship is explicit. The output must be detailed enough that a coding agent can create the database migrations directly from this document.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
- You are a Systems Architect translating business concepts into database structure
|
||||
- The Product Brief is your primary source — every business concept mentioned there must appear in the schema
|
||||
- Ask the user to validate your interpretation, not to design the schema themselves
|
||||
|
||||
### Step-Specific Rules:
|
||||
- Focus: Tables, columns, types, defaults, constraints, relationships, indexes
|
||||
- FORBIDDEN: Do not produce vague "data layer" descriptions. Every column must have a name and type.
|
||||
- FORBIDDEN: Do not skip nullable/default/constraint decisions
|
||||
- Approach: Extract entities from the Product Brief, propose schema, validate with user
|
||||
|
||||
## CONTEXT DEPENDENCIES:
|
||||
- Product Brief (Steps 1-12): Business concepts, user types, product features
|
||||
- Technology Stack (Step 28): Database choice constrains types and features
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Extract Entities from Product Brief
|
||||
|
||||
Read the Product Brief and identify every noun that the system manages:
|
||||
- Users, accounts, organizations
|
||||
- The core business objects (projects, orders, content, products, etc.)
|
||||
- Supporting objects (settings, notifications, payments, etc.)
|
||||
- Reference data (categories, statuses, types)
|
||||
|
||||
Present the entity list: "Based on your Product Brief, these are the things your system manages: [list]. Missing anything?"
|
||||
|
||||
### 2. Define Each Table
|
||||
|
||||
For EVERY entity, define:
|
||||
|
||||
```
|
||||
Table: [entity_name]
|
||||
Description: [what this represents in the business]
|
||||
|
||||
| Column | Type | Nullable | Default | Constraint | Description |
|
||||
|--------|------|----------|---------|------------|-------------|
|
||||
| id | uuid | no | gen_random_uuid() | PK | |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
| created_at | timestamptz | no | now() | | |
|
||||
| updated_at | timestamptz | no | now() | | |
|
||||
```
|
||||
|
||||
### 3. Define Relationships
|
||||
|
||||
For every relationship between entities:
|
||||
- Type: one-to-one, one-to-many, many-to-many
|
||||
- Foreign key column and referenced table
|
||||
- Cascade behavior (on delete, on update)
|
||||
- Junction tables for many-to-many
|
||||
|
||||
### 4. Define Indexes
|
||||
|
||||
Based on expected query patterns:
|
||||
- Which columns will be searched/filtered frequently?
|
||||
- Composite indexes for common query combinations
|
||||
- Unique constraints for business rules (e.g., one active subscription per user)
|
||||
|
||||
### 5. Enumerate Data Types
|
||||
|
||||
Reference the chosen database and use exact types:
|
||||
- PostgreSQL: `text`, `integer`, `bigint`, `numeric(10,2)`, `timestamptz`, `uuid`, `jsonb`, `boolean`, `text[]`
|
||||
- SQLite: `TEXT`, `INTEGER`, `REAL`, `BLOB`
|
||||
- MySQL: `VARCHAR(255)`, `INT`, `DECIMAL(10,2)`, `DATETIME`, `JSON`
|
||||
|
||||
No vague "string" or "number" — exact database types only.
|
||||
|
||||
### 6. Release Phase Tagging
|
||||
|
||||
If the product has multiple release phases (MVP, v2, v3):
|
||||
- Tag each table and column with which phase introduces it
|
||||
- Phase 1 tables must be complete — later phases ADD columns/tables, never restructure
|
||||
- The schema should be designed so that all phases share the same foundation
|
||||
|
||||
Present: "Here's what exists in Phase 1 vs what gets added later. The key insight: we design the full schema now but only populate Phase 1 fields initially."
|
||||
|
||||
### 7. Validate with User
|
||||
|
||||
Present the complete schema and ask:
|
||||
- "Does every business concept from your Product Brief have a home in this schema?"
|
||||
- "Are there any entities I missed?"
|
||||
- "Do the relationships match how your business actually works?"
|
||||
|
||||
### 8. Design Log Update
|
||||
|
||||
Update design log with schema decisions.
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
Display: "**Select an Option:** [C] Continue to State Machines"
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN the user confirms the schema is complete will you proceed.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
- Every business entity from the Product Brief has a table
|
||||
- Every table has complete column definitions (name, type, nullable, default, constraints)
|
||||
- All relationships defined with foreign keys and cascade behavior
|
||||
- Indexes defined for expected query patterns
|
||||
- Release phases tagged
|
||||
- User confirmed the schema captures their business
|
||||
|
||||
### FAILURE:
|
||||
- Produced a "data layer overview" instead of actual table definitions
|
||||
- Left columns with vague types ("string", "number")
|
||||
- Missed entities mentioned in the Product Brief
|
||||
- Did not define relationships between tables
|
||||
- Generated schema without user validation
|
||||
|
||||
**LITMUS TEST:** Can a coding agent run `CREATE TABLE` statements directly from this output? If not, it's not done.
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
name: 'step-28b-state-machines'
|
||||
description: 'Define state machines for every entity with a lifecycle'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-28c-business-logic.md'
|
||||
workflowFile: '../workflow.md'
|
||||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
||||
# Step 28b: State Machines
|
||||
|
||||
## STEP GOAL:
|
||||
Define the state machine for every entity that has a lifecycle. Every status field in the database schema (from Step 28a) becomes a state machine with explicit states, transitions, triggers, and actions. If the product has release phases, document what each transition does in EACH phase.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
- You are a Systems Architect mapping business processes to state transitions
|
||||
- The database schema from Step 28a is your primary input — every `status` column becomes a state machine
|
||||
- Draw the states as ASCII diagrams so the user can visualize the flow
|
||||
|
||||
## CONTEXT DEPENDENCIES:
|
||||
- Database Schema (Step 28a): Every entity with a `status` column
|
||||
- Product Brief: Business process descriptions
|
||||
- Technology Stack (Step 28): Hosting/deployment constraints
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Identify Stateful Entities
|
||||
|
||||
From the database schema, list every table that has a `status` column:
|
||||
- "These entities have lifecycles: [list]. Each one needs a state machine."
|
||||
- Ask: "Are there any other processes that move through stages that I missed?"
|
||||
|
||||
### 2. For Each Entity, Define the State Machine
|
||||
|
||||
**Present as ASCII state diagram:**
|
||||
```
|
||||
draft ──→ active ──→ expiring ──→ expired
|
||||
│ │
|
||||
▼ ▼
|
||||
renewed lapsed
|
||||
```
|
||||
|
||||
**Then document as a transition table:**
|
||||
|
||||
| From → To | Trigger | What Happens |
|
||||
|-----------|---------|-------------|
|
||||
| draft → active | User confirms | Set start_date, schedule reminders |
|
||||
| active → expiring | 30 days before end | Send notification |
|
||||
| ... | ... | ... |
|
||||
|
||||
### 3. Per-Phase Actions (if product has release phases)
|
||||
|
||||
If the Product Brief describes progressive automation (e.g., manual → assisted → automated), document what each transition does in EACH phase:
|
||||
|
||||
| From → To | Trigger | Phase 1 (Manual) | Phase 2 (Assisted) | Phase 3 (Automated) |
|
||||
|-----------|---------|------------------|-------------------|---------------------|
|
||||
| delivered → active | Payment confirmed | Creator logs "they paid" | Stripe webhook | Stripe webhook |
|
||||
| expiring → expired | End date reached | Notification: "chase?" | "Want me to send offer?" | Auto-send offer |
|
||||
|
||||
**Key principle:** The states and transitions NEVER change between phases. Only the ACTION HANDLERS change. Same database, same state machine, different level of automation.
|
||||
|
||||
### 4. Feature Gate Pattern
|
||||
|
||||
If phases exist, document the gating pattern:
|
||||
|
||||
```
|
||||
function onTransition(entity, from, to):
|
||||
// Always happens (all phases):
|
||||
entity.status = to
|
||||
entity.updated_at = now()
|
||||
log_event(entity, from, to)
|
||||
|
||||
// Phase-gated actions:
|
||||
if feature_flag('phase_2_automation'):
|
||||
// Automated action
|
||||
else:
|
||||
// Manual reminder
|
||||
```
|
||||
|
||||
Present to user: "This pattern means you build once and unlock features by flipping flags. The database and state machine never change."
|
||||
|
||||
### 5. Edge Cases
|
||||
|
||||
For each state machine, ask about:
|
||||
- Can an entity move backward? (e.g., active → draft for corrections)
|
||||
- What happens on cancellation from any state?
|
||||
- What about simultaneous transitions? (e.g., payment received while in wrong state)
|
||||
- Timeout transitions (what if nothing happens for N days?)
|
||||
|
||||
### 6. Validate with User
|
||||
|
||||
Present all state machines and ask:
|
||||
- "Does this match how your business actually works?"
|
||||
- "Are there any states or transitions I missed?"
|
||||
- "Do the per-phase actions feel right?"
|
||||
|
||||
### 7. Design Log Update
|
||||
|
||||
Update design log with state machine decisions.
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
Display: "**Select an Option:** [C] Continue to Business Logic"
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN the user confirms all state machines are complete will you proceed.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
- Every status column from the schema has a state machine
|
||||
- State diagrams presented visually (ASCII)
|
||||
- Transition tables complete with triggers and actions
|
||||
- Per-phase action differences documented (if applicable)
|
||||
- Feature gate pattern documented
|
||||
- Edge cases addressed
|
||||
- User confirmed
|
||||
|
||||
### FAILURE:
|
||||
- Listed states without transitions
|
||||
- Described processes in prose instead of explicit state → state tables
|
||||
- Missed per-phase action differences
|
||||
- Did not address edge cases
|
||||
|
||||
**LITMUS TEST:** Can a developer implement the state machine as a function from this document, with every transition and its effects explicit? If not, it's not done.
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
|
@ -0,0 +1,189 @@
|
|||
---
|
||||
name: 'step-28c-business-logic'
|
||||
description: 'Define business logic, calculations, event handlers, and API surface'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-29-integrations.md'
|
||||
workflowFile: '../workflow.md'
|
||||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
||||
# Step 28c: Business Logic, Events & API
|
||||
|
||||
## STEP GOAL:
|
||||
Define the business logic layer: calculations, event system, scheduled jobs, webhook handlers, and the complete API surface. This step turns the database schema (28a) and state machines (28b) into the living system that connects them. The output must be specific enough that a coding agent can implement every handler and endpoint.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
- You are a Systems Architect defining the behavioral layer of the system
|
||||
- Schema + state machines are your inputs. Business logic is your output.
|
||||
- Write pseudocode for non-trivial calculations. Don't describe — specify.
|
||||
|
||||
## CONTEXT DEPENDENCIES:
|
||||
- Database Schema (Step 28a): The data structures
|
||||
- State Machines (Step 28b): The lifecycle flows
|
||||
- Product Brief: Business rules, pricing, calculations
|
||||
- Technology Stack (Step 28): API style (REST/GraphQL), language constraints
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Business Calculations
|
||||
|
||||
Extract every calculation from the Product Brief and document as pseudocode:
|
||||
|
||||
```
|
||||
function calculate_commission(payment, user):
|
||||
if user.tier == 'flex':
|
||||
rate = 0.05
|
||||
elif user.tier == 'pro':
|
||||
rate = 0.02
|
||||
elif user.tier == 'enterprise':
|
||||
rate = negotiated_rate(user)
|
||||
return payment.gross_amount * rate
|
||||
```
|
||||
|
||||
Ask: "What are the financial calculations, pricing rules, or formulas in your product?"
|
||||
|
||||
Document EVERY calculation — not just the obvious ones. Include:
|
||||
- Pricing calculations
|
||||
- Commission/fee calculations
|
||||
- Date calculations (expiry dates, reminder schedules)
|
||||
- Threshold calculations (when to trigger actions)
|
||||
- Scoring/ranking algorithms (if any)
|
||||
|
||||
### 2. Event System
|
||||
|
||||
Every system has events — things that happen that trigger other things. Document three categories:
|
||||
|
||||
**Scheduled Events (cron / background jobs):**
|
||||
|
||||
| Event | Frequency | Handler |
|
||||
|-------|-----------|---------|
|
||||
| check_expiring_X | Daily | Find all X where deadline approaching. Transition state. Send notification. |
|
||||
| ... | ... | ... |
|
||||
|
||||
**Webhook Events (external triggers):**
|
||||
|
||||
| Event | Source | Handler |
|
||||
|-------|--------|---------|
|
||||
| payment_succeeded | Stripe | Find entity. Update status. Create record. Notify user. |
|
||||
| ... | ... | ... |
|
||||
|
||||
**User Events (from UI / chat / API):**
|
||||
|
||||
| Event | Source | Handler |
|
||||
|-------|--------|---------|
|
||||
| entity_created | UI/API | Validate. Insert. Schedule follow-ups. |
|
||||
| ... | ... | ... |
|
||||
|
||||
For each handler, document:
|
||||
- What it checks (preconditions)
|
||||
- What it changes (state transitions, record creation)
|
||||
- What it triggers (notifications, follow-up events)
|
||||
- How it differs per release phase (if applicable)
|
||||
|
||||
### 3. Notification Rules
|
||||
|
||||
When does the system communicate with the user? Document every notification:
|
||||
|
||||
| Trigger | Channel | Message Pattern | Phase |
|
||||
|---------|---------|----------------|-------|
|
||||
| Usage right expiring in 30 days | Push + in-app | "DJI expires in 30 days — chase?" | All |
|
||||
| Invoice overdue 7 days | Email + in-app | "Nike hasn't paid — send reminder?" | 2+ |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
Include: timing rules (don't send at 3am), deduplication (don't remind twice for same thing), escalation (first reminder → second → urgent).
|
||||
|
||||
### 4. API Surface
|
||||
|
||||
Document every endpoint the system exposes:
|
||||
|
||||
**REST format:**
|
||||
| Method | Path | Purpose | Auth | Request | Response |
|
||||
|--------|------|---------|------|---------|----------|
|
||||
| POST | /api/auth/register | Create account | None | { email, password, name } | { user, token } |
|
||||
| POST | /api/chat | Send message to AI | Bearer | { message, attachments? } | SSE stream |
|
||||
| GET | /api/projects | List user's projects | Bearer | ?status=active&limit=20 | { projects[], total } |
|
||||
| POST | /api/projects | Create project | Bearer | { title, client_id, ... } | { project } |
|
||||
| PATCH | /api/projects/:id | Update project | Bearer | { status?, title?, ... } | { project } |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
**For EVERY entity in the schema, define at minimum:**
|
||||
- List (GET with filters and pagination)
|
||||
- Get single (GET by ID)
|
||||
- Create (POST)
|
||||
- Update (PATCH)
|
||||
- Delete/archive (DELETE or soft-delete)
|
||||
|
||||
**Plus any special endpoints:**
|
||||
- File upload
|
||||
- Export (CSV, PDF)
|
||||
- Bulk operations
|
||||
- Webhook receivers
|
||||
- MCP server endpoints (if applicable)
|
||||
|
||||
### 5. Authentication & Authorization
|
||||
|
||||
- Auth method (JWT, sessions, OAuth)
|
||||
- Token lifecycle (access token TTL, refresh token)
|
||||
- Role-based access (who can do what)
|
||||
- Row-level security rules (who sees what data)
|
||||
|
||||
### 6. AI Integration Spec (if applicable)
|
||||
|
||||
If the product has AI features:
|
||||
- Which endpoints involve AI
|
||||
- Model selection logic (which model for which task)
|
||||
- Tool definitions (what tools can the AI call)
|
||||
- Conversation memory strategy (full history, summarized, window)
|
||||
- Cost management (model routing by complexity)
|
||||
- Streaming approach (SSE, WebSocket)
|
||||
|
||||
### 7. Validate with User
|
||||
|
||||
Present the complete business logic spec and ask:
|
||||
- "Does this capture every rule in your business?"
|
||||
- "Are there calculations I missed?"
|
||||
- "Does the API surface cover every action users need?"
|
||||
- "Are the notification rules right — not too many, not too few?"
|
||||
|
||||
### 8. Design Log Update
|
||||
|
||||
Update design log with business logic decisions.
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
Display: "**Select an Option:** [C] Continue to Integrations"
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN the user confirms the business logic is complete will you proceed.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
- Every calculation documented as pseudocode
|
||||
- Event system complete (scheduled, webhook, user events)
|
||||
- Notification rules defined with timing and channels
|
||||
- API surface covers every entity and special operation
|
||||
- Auth and authorization specified
|
||||
- AI integration documented (if applicable)
|
||||
- User confirmed
|
||||
|
||||
### FAILURE:
|
||||
- Described business rules in prose instead of pseudocode/tables
|
||||
- Listed API endpoints without request/response shapes
|
||||
- Missed event handlers for state transitions defined in Step 28b
|
||||
- Did not address notification timing and deduplication
|
||||
- Generated API surface without user validation
|
||||
|
||||
**LITMUS TEST:** Can a coding agent implement every endpoint, every handler, and every calculation from this document alone? Can it write the cron jobs, the webhook receivers, the notification logic? If not, it's not done.
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
|
@ -4,6 +4,7 @@ description: 'Document required integrations and third-party services'
|
|||
|
||||
# File References
|
||||
nextStepFile: './step-30-contact-strategy.md'
|
||||
# Note: Step 29 now follows Step 28c (business logic), not Step 28 directly
|
||||
workflowFile: '../workflow.md'
|
||||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: 'step-32-create-platform-document'
|
||||
description: 'Complete the Platform Requirements document and prepare for next steps'
|
||||
description: 'Finalize the Platform Requirements as a complete build specification'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-33-analyze-brief.md'
|
||||
|
|
@ -8,129 +8,129 @@ workflowFile: '../workflow.md'
|
|||
activityWorkflowFile: '../workflow.md'
|
||||
---
|
||||
|
||||
# Step 32: Create Platform Requirements Document
|
||||
# Step 32: Finalize Platform Requirements
|
||||
|
||||
## STEP GOAL:
|
||||
Complete the Platform Requirements document, document maintenance ownership, and prepare for next steps.
|
||||
Complete the Platform Requirements document and verify it passes the build specification litmus test. This is the final gate before the document ships — everything must be actionable.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
- You are a Strategic Business Analyst finalizing platform requirements for handoff
|
||||
- If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- We engage in collaborative dialogue, not command-response
|
||||
- You bring structured thinking and facilitation skills, user brings domain expertise and product vision
|
||||
- Maintain collaborative and strategic tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
- Focus: Review completeness, document maintenance ownership, development handoff notes, confirm
|
||||
- FORBIDDEN: Do not skip maintenance ownership documentation
|
||||
- Approach: Review all sections, capture maintenance plan, present summary, confirm
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
- Primary goal: Platform Requirements document finalized and confirmed
|
||||
- Save/document outputs appropriately
|
||||
- Avoid generating content without user input
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
- Available context: Steps 27-31 (tech stack, integrations, contact, multilingual, SEO)
|
||||
- Focus: Synthesis and practical handoff
|
||||
- Limits: Finalizing what was captured, not adding major new elements
|
||||
- Dependencies: Steps 27-31 completed
|
||||
- You are a Systems Architect performing final review of a build specification
|
||||
- Your job is quality assurance — find gaps that would block a coding agent
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Review Completeness
|
||||
### 1. Completeness Checklist
|
||||
|
||||
Check that all sections are filled:
|
||||
- [ ] Technology Stack
|
||||
- [ ] Plugin/Package Stack
|
||||
- [ ] Integrations
|
||||
- [ ] Contact Strategy
|
||||
- [ ] UX Constraints
|
||||
- [ ] Multilingual Requirements
|
||||
- [ ] SEO Requirements
|
||||
- [ ] Maintenance & Ownership
|
||||
Verify all sections are present and substantive:
|
||||
|
||||
### 2. Document Maintenance Ownership
|
||||
**Architecture & Technology:**
|
||||
- [ ] Architecture pattern and system diagram
|
||||
- [ ] Frontend framework, styling, state management
|
||||
- [ ] Backend language, framework, API style
|
||||
- [ ] Database choice with exact column types
|
||||
- [ ] Hosting, CI/CD, environments
|
||||
|
||||
Ask: "Who will maintain the site after launch?"
|
||||
- Content updates - client or agency?
|
||||
- Technical maintenance - developer or managed?
|
||||
- Plugin updates - automatic or manual review?
|
||||
**Build Specification (the new core):**
|
||||
- [ ] Complete database schema — every table, every column, types, defaults, constraints, relationships
|
||||
- [ ] State machines — every stateful entity has states, transitions, triggers, per-phase actions
|
||||
- [ ] Business logic — every calculation as pseudocode, not prose
|
||||
- [ ] Event system — scheduled jobs, webhook handlers, user events with preconditions and effects
|
||||
- [ ] Notification rules — triggers, channels, timing, deduplication
|
||||
- [ ] API surface — every endpoint with method, path, auth, request shape, response shape
|
||||
- [ ] Authentication and authorization — method, token lifecycle, roles, RLS rules
|
||||
|
||||
Fill in Maintenance & Ownership section.
|
||||
**Integration & Operations:**
|
||||
- [ ] Third-party integrations with purpose and config
|
||||
- [ ] Contact/communication strategy
|
||||
- [ ] Multilingual requirements (if applicable)
|
||||
- [ ] SEO technical requirements (if applicable)
|
||||
- [ ] Release phase feature gating (if applicable)
|
||||
- [ ] Maintenance ownership
|
||||
|
||||
### 3. Development Handoff Notes
|
||||
### 2. The Litmus Test
|
||||
|
||||
Capture any important notes for developers:
|
||||
- Environment setup requirements
|
||||
- Deployment process expectations
|
||||
- Special considerations
|
||||
Read through the entire document and answer these questions honestly:
|
||||
|
||||
### 4. Present Summary
|
||||
**Can a coding agent build from this?**
|
||||
1. Can it create ALL database migrations from the schema section? (Every table, column, type, constraint)
|
||||
2. Can it implement ALL state machines from the state machine section? (Every transition, trigger, action)
|
||||
3. Can it write ALL API endpoints from the API section? (Every route, request, response)
|
||||
4. Can it implement ALL business calculations from the business logic section?
|
||||
5. Can it set up ALL scheduled jobs from the event system?
|
||||
6. Can it handle ALL webhooks from the webhook section?
|
||||
7. Can it send ALL notifications with correct timing and content?
|
||||
|
||||
Show the user a summary table:
|
||||
**If ANY answer is "no" — the document has gaps. Go back and fill them.**
|
||||
|
||||
Present the litmus test results to the user:
|
||||
```
|
||||
Build Specification Litmus Test:
|
||||
✓ Database migrations: [complete/gaps in X]
|
||||
✓ State machines: [complete/gaps in X]
|
||||
✓ API endpoints: [complete/gaps in X]
|
||||
✓ Business logic: [complete/gaps in X]
|
||||
✓ Event handlers: [complete/gaps in X]
|
||||
✓ Webhooks: [complete/gaps in X]
|
||||
✓ Notifications: [complete/gaps in X]
|
||||
```
|
||||
|
||||
### 3. Summary
|
||||
|
||||
Present a high-level summary table:
|
||||
|
||||
```
|
||||
Platform Requirements Summary
|
||||
---
|
||||
Tech Stack: [CMS/Framework]
|
||||
Styling: [Approach]
|
||||
Languages: [List]
|
||||
Contact: [Primary method]
|
||||
SEO: [Plugin choice]
|
||||
Key Constraint: [Most important UX constraint]
|
||||
─────────────────────────────
|
||||
Architecture: [pattern] — [frontend] + [backend] + [database]
|
||||
Tables: [N] database tables defined
|
||||
State Machines: [N] entity lifecycles mapped
|
||||
API Endpoints: [N] endpoints specified
|
||||
Event Handlers: [N] scheduled + [N] webhook + [N] user events
|
||||
Integrations: [list]
|
||||
Release Phases: [N] phases with feature gating
|
||||
```
|
||||
|
||||
### 5. Confirm and Save
|
||||
### 4. Confirm and Save
|
||||
|
||||
Ask: "Does this capture all the platform decisions?"
|
||||
- If changes needed, update document
|
||||
- If complete, finalize
|
||||
Ask: "This document should enable a coding agent to build the entire platform without asking questions. Does it?"
|
||||
|
||||
### 6. Next Steps Guidance
|
||||
- If gaps found: go back to the relevant step and fill them
|
||||
- If complete: finalize the document
|
||||
|
||||
Explain what's next:
|
||||
- "Platform Requirements will constrain UX design in Phase 4"
|
||||
- "Developers will use this in Phase 6 for handoff"
|
||||
### 5. Design Log Update
|
||||
|
||||
Update design log marking Platform Requirements as complete.
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
Display: "**Select an Option:** [C] Continue to next step"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Load, read entire file, then execute {nextStepFile}
|
||||
- IF M: Return to {workflowFile} or {activityWorkflowFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
Display: "**Select an Option:** [C] Continue to Analysis"
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
ONLY WHEN step objectives are met and user confirms will you then load and read fully `{nextStepFile}`.
|
||||
ONLY WHEN the litmus test passes and user confirms will you proceed.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
- All sections reviewed for completeness
|
||||
- Maintenance ownership documented
|
||||
- Development handoff notes captured
|
||||
- All checklist items verified as present
|
||||
- Litmus test passed — every section is actionable by a coding agent
|
||||
- Summary presented and confirmed by user
|
||||
- Document finalized and saved
|
||||
- Document finalized
|
||||
|
||||
### FAILURE:
|
||||
- Skipped maintenance ownership
|
||||
- Left sections incomplete
|
||||
- Did not present summary for confirmation
|
||||
- Passed a document with vague sections ("we'll figure out the API later")
|
||||
- Did not run the litmus test
|
||||
- Left the document as a planning document instead of a build specification
|
||||
- Accepted "tech stack + integrations list" as complete Platform Requirements
|
||||
|
||||
**THE GOLDEN RULE:** A Platform Requirements document that a coding agent can't build from is not a Platform Requirements document. It's a wish list.
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
|
|
|||
Loading…
Reference in New Issue