Workflow Usage Guide: Practical Examples#

Date: 2025-11-09 Related: Setup Conversation Purpose: Provide step-by-step examples of using the documentation-driven development workflows

🎯 Overview#

This guide shows practical examples of executing the complete workflow from requirements through code generation using the prompts and instructions created in this template.

Complete Workflow Example: User Authentication#

Let's walk through implementing a user authentication feature from scratch.

Stage 0: Environment Setup#

Prompt:

Check the UV environment following .github/instructions/uv-environment-setup.instructions.md.
If environment doesn't exist, create it.

Expected outcome:

✅ UV environment exists
✅ Ready to use uv add for packages

Stage 1: Requirements → Specification#

Using orchestration prompt (recommended):

Execute the workflow-requirements-to-spec prompt for docs/requirements/req-user-auth.md with threat model scope per-requirement

This single command will:

✅ Generate docs/specifications/spec_ser-auth.md
✅ Create docs/diagrams/threat-model_user-auth.md
✅ Create docs/diagrams/architecture_user-auth.md
✅ Run specification quality review
✅ Update cross-reference table and index
✅ Create execution log

Expected output summary:

✅ Requirements → Specification Workflow Complete

📁 Files Created:
- [docs/specifications/spec_user-auth.md](../specifications/spec_user-auth.md)
- [docs/diagrams/threat-model_user-auth.md](../diagrams/threat-model_user-auth.md)
- [docs/diagrams/architecture-user-auth.md](../diagrams/architecture_user-auth.md)

📝 Files Updated:
- [docs/SPEC-CROSS-REFERENCE.md](../SPEC-CROSS-REFERENCE.md)
- [docs/INDEX.md](../INDEX.md)

🔒 CodeGuard Files Referenced:
- [codeguard-0-authentication-mfa.instructions.md](../../.github/instructions/codeguard-0-authentication-mfa.instructions.md)
- [codeguard-0-input-validation-injection.instructions.md](../../.github/instructions/codeguard-0-input-validation-injection.instructions.md)
- [codeguard-0-session-management-and-cookies.instructions.md](../../.github/instructions/codeguard-0-session-management-and-cookies.instructions.md)

📋 Quality Review: ✅ PASSED

⏳ Next Step: Human review and approval

Human review checkpoint: Review the generated files and approve to proceed.

Stage 2: Specification → Code#

Using orchestration prompt (recommended):

Execute the workflow-spec-to-code prompt for docs/specifications/spec_user-auth.md

This single command will:

✅ Implement code using TDD (RED-GREEN-REFACTOR cycles)
✅ Generate tests before code
✅ Apply CodeGuard security rules
✅ Run security review
✅ Run quality validation (pytest, coverage, ruff)
✅ Update documentation
✅ Create execution log

Expected output summary:

✅ Specification → Code Workflow Complete

📁 Files Created:
- src/auth/login.py
- src/auth/session.py
- test/test_auth/test_login.py
- test/test_auth/test_session.py

🧪 Test Results:
- Total tests: 24
- Passed: 24 ✅
- Coverage: 94%

🔒 CodeGuard Files Applied:
- [codeguard-0-authentication-mfa.instructions.md](../../.github/instructions/codeguard-0-authentication-mfa.instructions.md)
- [codeguard-0-input-validation-injection.instructions.md](../../.github/instructions/codeguard-0-input-validation-injection.instructions.md)
- [codeguard-0-session-management-and-cookies.instructions.md](../../.github/instructions/codeguard-0-session-management-and-cookies.instructions.md)

📋 Quality Review: ✅ PASSED
🔒 Security Review: ✅ PASSED

⏳ Next Step: Human code review and approval

Using Workflow Orchestration Prompts#

Benefits#

🚀 Fast: Single command runs entire workflow
✅ Complete: Includes all quality gates
📋 Traceable: Creates comprehensive logs
🔒 Secure: Automatically applies CodeGuard

Requirements → Specification Workflow#

Prompt file: workflow-requirements-to-spec.prompt.md

Usage with Claude Code:

Execute the workflow-requirements-to-spec prompt for docs/requirements/req-{name}.md with threat model scope {per-requirement|high-level-aggregate|grouped-by-feature}

Usage with GitHub Copilot:

@workspace Follow @.github/prompts/workflow-requirements-to-spec.prompt.md to generate complete specification from @docs/requirements/req-{name}.md

What it does:

Generates specification
Creates threat model
Creates architecture diagram
Runs specification quality review
Updates cross-reference table
Creates execution log

Specification → Code Workflow#

Prompt file: workflow-spec-to-code.prompt.md

Usage with Claude Code:

Execute the workflow-spec-to-code prompt for docs/specifications/spec_{name}.md

Usage with GitHub Copilot:

@workspace Follow @.github/prompts/workflow-spec-to-code.prompt.md to implement @docs/specifications/spec_{name}.md

What it does:

Reviews specification
Implements using TDD workflow
Runs security review
Runs quality validation
Conducts post-test review
Updates documentation
Creates execution log

Using Individual Prompts#

When to Use Individual Prompts#

🎯 Specific task: Only need one operation
🔄 Iterating: Regenerating one component
📚 Learning: Understanding each step

Generate Specification#

Prompt file: generate-spec-from-requirement.prompt.md

Use the generate-spec-from-requirement prompt for docs/requirements/req-{name}.md

Outputs:

docs/specifications/spec_{name}.md
Updates to cross-reference table

Create Threat Model#

Prompt file: create-threat-model.prompt.md

Use the create-threat-model prompt for docs/requirements/req-{name}.md with scope per-requirement

Outputs:

docs/diagrams/threat-model-{name}.md
STRIDE analysis
CodeGuard references

Create Architecture Diagram#

Prompt file: create-architecture-diagram.prompt.md

Use the create-architecture-diagram prompt for docs/specifications/spec_{name}.md

Outputs:

docs/diagrams/architecture-{name}.md
Mermaid diagrams
Security annotations

Generate Code with TDD#

Prompt file: generate-code-from-spec.prompt.md

Use the generate-code-from-spec prompt for docs/specifications/spec_{name}.md

Outputs:

Source files in src/
Test files in test/
Execution log with TDD cycles documented

Quality Review at Each Stage#

Requirements Stage Quality Review#

Reference: Quality Checklists - Requirements Stage

Prompt:

Conduct requirements stage quality review for docs/requirements/req-{name}.md following .github/instructions/quality-checklists.md

Key checks:

✅ Problem statement clear
✅ Acceptance criteria measurable
✅ Dependencies identified
✅ Security considerations noted

Specification Stage Quality Review#

Reference: Quality Checklists - Specification Stage

Prompt:

Conduct specification stage quality review for docs/specifications/spec_{name}.md following .github/instructions/quality-checklists.md

Key checks:

✅ Architecture defined
✅ TDD planning complete
✅ Threat model created
✅ CodeGuard files referenced
✅ Filename includes -tdd suffix

Code Generation Stage Quality Review#

Reference: Quality Checklists - Code Generation Stage

Prompt:

Conduct code generation stage quality review for src/{module}/ following .github/instructions/quality-checklists.md

Key checks:

✅ All tests pass
✅ Coverage ≥ 90%
✅ Ruff checks pass
✅ Docstrings follow standards
✅ CodeGuard compliance verified

Manual commands:

# Run tests
pytest -v

# Check coverage
pytest --cov=src --cov-report=term

# Run ruff
ruff check src/ test/
ruff format src/ test/

Troubleshooting Common Issues#

Issue: Quality Review Fails#

Symptom:

❌ Quality review failed: Test coverage only 65% (threshold 90%)

Solution:

# Identify uncovered lines
pytest --cov=src --cov-report=html
open htmlcov/index.html

# Add tests for missing scenarios
# Re-run quality review

Issue: Security Review Fails#

Symptom:

❌ Security review failed: Hardcoded credential found

Solution:

Review relevant CodeGuard file
Move credentials to environment variables
Update code to use os.getenv()
Add to error resolution KB
Re-run security review

Issue: Tests Fail After Refactoring#

Symptom: Tests pass in GREEN but fail after REFACTOR phase

Solution:

Review changes made during refactoring
Ensure logic hasn't changed
Check test expectations are still valid
Add debug logging temporarily
Request human guidance if stuck

Issue: Prompt Not Executing#

Symptom: AI doesn't recognize the prompt reference

Solution:

Read .github/prompts/{prompt-file}.prompt.md and execute that prompt for {target-file}

Quick Reference#

Workflow Orchestration#

# Requirements → Specification (complete)
Execute workflow-requirements-to-spec prompt for docs/requirements/{name}.md with scope per-requirement

# Specification → Code (complete)
Execute workflow-spec-to-code prompt for docs/specifications/spec_{name}.md

Individual Operations#

# Generate specification
Use generate-spec-from-requirement prompt for docs/requirements/{name}.md

# Create threat model
Use create-threat-model prompt for docs/requirements/{name}.md with scope per-requirement

# Create architecture diagram
Use create-architecture-diagram prompt for docs/specifications/spec_{name}.md

# Generate code with TDD
Use generate-code-from-spec prompt for docs/specifications/spec_{name}.md

Quality Reviews#

# Requirements quality review
Conduct requirements stage quality review for docs/requirements/{name}.md following .github/instructions/quality-checklists.md

# Specification quality review
Conduct specification stage quality review for docs/specifications/spec_{name}.md following .github/instructions/quality-checklists.md

# Code quality review
Conduct code generation stage quality review for src/{module}/ following .github/instructions/quality-checklists.md

Manual Quality Checks#

# Run all tests
pytest -v

# Check coverage with report
pytest --cov=src --cov-report=term --cov-report=html

# Ruff linting
ruff check src/ test/

# Ruff formatting
ruff format src/ test/

# Combined check
pytest -v && pytest --cov=src && ruff check src/ test/

Setup Conversation - Why this structure exists
Master Workflow - Complete workflow overview
Quality Checklists - All stage checklists
All Workflow Prompts - Orchestration and individual prompts
TDD Workflow - RED-GREEN-REFACTOR process
Output Format - Log format specification

Last Updated: 2025-11-09

Workflow Usage Guide: Practical Examples#

🎯 Overview#

📋 Table of Contents#

Complete Workflow Example: User Authentication#

Stage 0: Environment Setup#

Stage 1: Requirements → Specification#

Stage 2: Specification → Code#

Using Workflow Orchestration Prompts#

Benefits#

Requirements → Specification Workflow#

Specification → Code Workflow#

Using Individual Prompts#

When to Use Individual Prompts#

Generate Specification#

Create Threat Model#

Create Architecture Diagram#

Generate Code with TDD#

Quality Review at Each Stage#

Requirements Stage Quality Review#

Specification Stage Quality Review#

Code Generation Stage Quality Review#

Troubleshooting Common Issues#

Issue: Quality Review Fails#

Issue: Security Review Fails#

Issue: Tests Fail After Refactoring#

Issue: Prompt Not Executing#

Quick Reference#

Workflow Orchestration#

Individual Operations#

Quality Reviews#

Manual Quality Checks#

Related Documentation#