srs-workflow
Full SRS workflow: Brainstorm → Spec → Plan (per-section files) → User Review → SRS Generation → Validation → Improvement Report → Context Save. Use when user provides a project topic and wants a comp
SKILL.md.codex/skills/srs-workflow/SKILL.md
GitHubsrs-workflow — Full SRS Workflow
Phase 0 Topic Intake
Phase 1 Deep Brainstorm ← multi-round, categorized, options-driven
Phase 2 Spec Writing ← no word limit
Phase 3 Options Gate ← user chooses next action
Phase 4 Plan Writing ← 1 .md file per SRS section
Phase 5 User Review ← iterate until approved
Phase 6 SRS Generation ← 1 .md file per section, full detail
Phase 7 Auto-Validate ← .codex/scripts/srs_validator.py
Phase 8 Improvement Report
Phase 9 Context Save
Output directory: projects/{slug}/
Phase 0 — Topic Intake
Receive the user's topic (1 sentence to 1 paragraph). Do NOT ask questions yet.
Identify:
- Domain (e-commerce, healthcare, fintech, internal tool, SaaS, etc.)
- Scale signals (startup, enterprise, MVP, etc.)
- Any constraints mentioned
Echo back a 3-line summary:
Topic: {topic}
Domain: {detected domain}
Scale: {detected scale or "unknown"}
Then state: "Starting deep brainstorm. I will ask questions by category before writing anything." Proceed to Phase 1.
Phase 1 — Deep Brainstorm
Hard rule: AI must not proceed to Phase 2 until it can confidently answer ALL of:
- Who are ALL actors (primary + secondary + external systems)?
- What are ALL core features (not just mentioned ones — infer and confirm)?
- What are the explicit system boundaries (in scope / out of scope)?
- What are the technical constraints?
- What are the business rules and compliance requirements?
Load .codex/skills/srs-workflow/references/brainstorm-guide.md for domain-specific question sets.
Round structure
Each round: ask ONE category of questions. Maximum 5 questions per round. Present concrete options wherever possible — never ask open-ended questions when a multiple-choice with "Other" covers the space.
Mandatory rounds (in order):
Round 1 — Actors & Users Ask about: primary users, secondary users, admin roles, external systems/APIs. For each actor type: present role options with descriptions. Wait for answers.
Round 2 — Core Features Present a feature checklist derived from the domain + topic. For each feature cluster: show sub-options (e.g., authentication: email/password | OAuth | SSO | all). Mark user selections as [CONFIRMED]. Infer likely features not mentioned — ask to confirm or reject. Wait for answers.
Round 3 — Scope Boundary Present a two-column table: proposed IN scope vs. proposed OUT scope. Ask user to move items or add new ones. Hard-block on scope: NEVER proceed without explicit in/out boundary. Wait for answers.
Round 4 — Technical Constraints Ask about: tech stack, hosting, existing systems to integrate, security/compliance standards, performance targets (give numeric examples), timeline/budget signals. Wait for answers.
Round 5 — Business Rules & Edge Cases Ask about: data ownership, roles/permissions model, pricing/billing logic (if applicable), regulatory requirements, key failure scenarios the system must handle gracefully. Wait for answers.
After Round 5: Run completeness check:
- Any actor still undefined? → ask NOW before proceeding.
- Any feature with unclear scope? → ask NOW.
- Missing NFR baseline? → ask NOW.
[GATE] Only proceed to Phase 2 when completeness check passes with zero open items. State: "Brainstorm complete. I now have enough information to write the spec. Proceeding."
Phase 2 — Spec Writing
Write projects/{slug}/spec.md using the spec template structure.
No word limit. Write every section fully — do not summarize or truncate.
- Every actor: full description, access rights, experience level
- Every feature: stated in user's words + AI-expanded detail
- Every constraint: verbatim + implication
- In/Out scope table: exhaustive
- Business rules: numbered, precise
- NFR targets: numeric where confirmed, [TBD with context] where not
After writing, output:
Spec written: projects/{slug}/spec.md
Sections: §1 ... §N
Word count: ~{N}
Proceed to Phase 3.
Phase 3 — Options Gate
Present the following menu:
Spec is ready. What would you like to do next?
A) Write plan → break SRS into per-section plan files, then review
B) Re-read spec → show full spec.md content for review/editing
C) Adjust brainstorm → return to Phase 1 to add/change requirements
D) Jump to SRS → skip planning, generate SRS directly (not recommended)
Wait for user choice. Route accordingly. B → display spec.md, then return to Phase 3. C → return to Phase 1 Round that covers the gap. D → skip to Phase 6. A → proceed to Phase 4.
Phase 4 — Plan Writing
Load .codex/skills/srs-workflow/references/plan-structure-guide.md.
Create one plan file per SRS section under projects/{slug}/plan/:
plan/
00-overview.md
01-introduction.md
02-overall-description.md
03-01-external-interfaces.md
03-02-functional-requirements.md
03-03-performance.md
03-04-database.md
03-05-design-constraints.md
03-06-system-attributes.md
03-07-other-requirements.md
appendix-a-glossary.md
appendix-b-open-issues.md
For each file:
- Write the full planned content for that SRS section
- Include: what will be written, every sub-item, FR list with "shall" stubs, NFR targets
- No word limit — plan files are the blueprint, they must be unambiguous
- Tag any item still needing user input:
[NEEDS USER INPUT: {what}]
After all plan files are written, output a summary table:
| File | Section | FRs planned | NFRs planned | Open items |
|------|---------|------------|--------------|------------|
Proceed to Phase 5.
Phase 5 — User Review
Present summary table from Phase 4. Then ask:
Plan is ready for review. What would you like to do?
A) Approve plan → proceed to SRS generation
B) Modify section → specify which section(s) to change
C) Add features → return to Phase 1 Round 2
D) Show full plan file → specify which file to display
If user modifies: update the relevant plan file(s) and return to this gate. [GATE] Only proceed to Phase 6 on explicit "Approve plan" (option A).
When approved, state: "Plan approved. Beginning SRS generation."
Phase 6 — SRS Generation
Generate SRS section by section, each as its own file under projects/{slug}/srs/:
srs/
01-introduction.md
02-overall-description.md
03-01-external-interfaces.md
03-02-functional-requirements.md
03-03-performance.md
03-04-database.md
03-05-design-constraints.md
03-06-system-attributes.md
03-07-other-requirements.md
appendix-a-glossary.md
appendix-b-open-issues.md
Load and follow .codex/skills/srs-generator/references/srs-template.md for each section's format.
FR format (mandatory):
FR-NN [Essential|Conditional|Optional]
Requirement: The system shall {verb} {object} when {condition}.
Actor / Precondition / Given / When / Then / Source
NFR format: ISO/IEC 25023 Quality Attribute Scenario — numeric Response Measure only.
No word limit. Each file must be complete. A full SRS across all files may reach 300+ pages — this is normal and expected.
Also generate projects/{slug}/srs/00-master-index.md linking all section files with word counts.
Proceed to Phase 7.
Phase 7 — Auto-Validate
Run the validator across the whole SRS directory at once:
python .codex/scripts/srs_validator.py --dir projects/{slug}/srs/
Output the full validation table. Then summarize:
## Validation Results
Overall: COMPLIANT | PARTIALLY COMPLIANT | NON-COMPLIANT
Errors: N (must fix before proceeding)
Warnings: N (captured in Phase 8 report)
For each ERROR: fix the affected SRS section file immediately, then re-run the validator. Do not leave any ERROR unresolved. WARN items do not block — capture in Phase 8.
Proceed to Phase 8.
Phase 8 — Improvement Report
Write projects/{slug}/improvement-report.md:
- Deferred features — items marked out-of-scope but flagged as likely future needs
- Technical risks — NFRs with [TBD] targets, integration unknowns, compliance gaps
- Refinement suggestions — FRs that could be split further, NFRs needing real load-test data
- Next version candidates — features users mentioned but explicitly deferred
- Validation warnings — WARN items from Phase 7 that should be resolved before dev
No word limit. Be specific — reference exact FR/NFR IDs, section numbers, and user quotes from brainstorm.
Proceed to Phase 9.
Phase 9 — Context Save
Write projects/{slug}/_context/:
_context/
vision.md ← project goals, problem statement, success metrics
features.md ← confirmed in/out scope feature list
tech_stack.md ← confirmed tech constraints
glossary.md ← all terms defined in Appendix A
quality_standards.md← confirmed NFR numeric targets
session-notes.md ← key decisions made, open questions, next steps
Then output final summary:
Workflow complete.
Project: {name}
Location: projects/{slug}/
SRS files: {N} section files
FRs: {total FR count}
NFRs: {total NFR count}
Verdict: {COMPLIANT | PARTIALLY COMPLIANT}
Open items: {count} (see appendix-b-open-issues.md)
Next step: share projects/{slug}/srs/ with your dev team.