AI Unified Process - stack-agnostic core methodology (requirements, entity model, use cases)

GitHub stars
37

Install

/plugin install aiup-core@aiup-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add martinellich/aiup-marketplace.

Contents

Discovered from source

Skills 4

Entity Model

Instructions

Create or update the entity model at docs/entity_model.md based on docs/requirements.md. The document contains an ER diagram and attribute tables.

DO NOT

  • Add attributes/columns to the Mermaid diagram
  • Write prose descriptions like "Key attributes: name, email..."
  • Create a "Relationships" table
  • Skip the attribute tables

Document Structure

# Entity Model

## Entity Relationship Diagram

```mermaid
erDiagram
    ROOM_TYPE ||--o{ ROOM : "categorizes"
    GUEST ||--o{ RESERVATION : "makes"

ENTITY_NAME

One sentence describing the entity.

AttributeDescriptionData TypeLength/PrecisionValidation Rules
id...Long19Primary Key, Sequence
...............

Required Format for Each Entity

Every entity MUST have:

  1. A ### heading with ENTITY_NAME
  2. One sentence description
  3. An attribute table with exactly 5 columns

Example Entity

ROOM_TYPE

Defines categories of rooms with shared characteristics.

AttributeDescriptionData TypeLength/PrecisionValidation Rules
idUnique identifierLong19Primary Key, Sequence
nameName of the room typeString50Not Null, Unique
descriptionDetailed descriptionString500Optional
capacityMaximum number of guestsInteger10Not Null, Min: 1, Max: 10
pricePrice per night in CHFDecimal10,2Not Null, Min: 0

Mermaid Diagram Rules

  • Show entity names and relationships ONLY
  • NO attributes inside entity blocks
  • Use relationship syntax: ENTITY_A ||--o{ ENTITY_B : "relationship"

Validation Rules Reference

Use these values in the "Validation Rules" column (never leave empty):

Attribute TypeValidation Rules Value
Primary keyPrimary Key, Sequence
Required fieldNot Null
Unique fieldNot Null, Unique
Foreign keyNot Null, Foreign Key (TABLE.id)
Optional fieldOptional
With rangeNot Null, Min: X, Max: Y
With valuesNot Null, Values: A, B, C
EmailNot Null, Format: Email

Data Types Reference

Data TypeLength/PrecisionUsage
Long19IDs, foreign keys
Stringvaries (50-500)Text fields
Integer10Whole numbers
Decimal10,2Currency, percentages
Boolean1True/false flags
Date-Date only
DateTime-Date and time

Multi-Column Constraints

If validation spans multiple columns, add after the table:

Constraints: Check-out date must be after check-in date.

Workflow

  1. Read the requirements document
  2. Use TodoWrite to create a task for each entity
  3. Write the document header and ER diagram (relationships only)
  4. For each entity:
    • Write ### heading
    • Write one sentence description
    • Write attribute table with 5 columns
    • Add constraints if needed
    • Mark todo complete
  5. Validate the document:
    • Every entity in the ER diagram has a corresponding attribute table section
    • Every attribute table has exactly 5 columns
    • No attributes appear inside the Mermaid diagram entity blocks
    • All foreign keys reference existing entities
    • All validation rules use values from the Validation Rules Reference

Requirements

Instructions

Create or update the requirements catalog at docs/requirements.md based on docs/vision.md. The document contains functional requirements, non-functional requirements, and constraints organized as Markdown tables.

DO NOT

  • Mix requirement types in a single table
  • Skip the user story format for functional requirements
  • Use duplicate IDs across requirement types
  • Leave the Status column empty

Requirement Types

Functional Requirements (FR)

Define what the system should do. Always use the user story format:

Format: As a [role], I want [goal] so that [benefit].

IDTitleUser StoryPriorityStatus
FR-001Create TaskAs a project manager, I want to create tasks so that I can track work items.HighOpen
FR-002Assign TaskAs a project manager, I want to assign tasks to team members so that work is distributed.HighOpen
FR-003Filter TasksAs a team member, I want to filter tasks by status so that I can focus on relevant items.MediumOpen

Non-Functional Requirements (NFR)

Define quality attributes. Must be measurable.

IDTitleRequirementCategoryPriorityStatus
NFR-001Response TimeAll page loads must complete within 2 seconds.PerformanceHighOpen
NFR-002AvailabilitySystem must maintain 99.9% uptime during business hours.AvailabilityHighOpen
NFR-003Concurrent UsersSystem must support 100 concurrent users without degradation.ScalabilityMediumOpen
NFR-004Data EncryptionAll data in transit must use TLS 1.3 encryption.SecurityHighOpen

Constraints (C)

Define limitations and boundaries imposed on the solution.

IDTitleConstraintCategoryPriorityStatus
C-001Runtime PlatformBackend must run on Java 21 LTS.TechnicalHighOpen
C-002Database PlatformSystem must use PostgreSQL 16.TechnicalHighOpen
C-003Browser SupportUI must support Chrome, Firefox, and Safari (latest 2 versions).TechnicalHighOpen
C-004Budget LimitTotal development cost must not exceed $50,000.BusinessHighOpen
C-005DeadlineSystem must be production-ready by Q2 2025.ScheduleHighOpen

Reference

See REFERENCE.md for ID prefixes, priority levels, status values, NFR categories, and constraint categories.

Requirement Quality Checks

Every requirement must pass these checks before finalizing:

CheckRuleBad ExampleGood Example
MeasurableNFRs must have a number or threshold"System should be fast""Pages load within 2 seconds"
SingularOne requirement per row"System must log in and export data"Split into FR-001 and FR-002
UnambiguousNo subjective terms"User-friendly interface""WCAG 2.1 AA compliant"
TestableCan write a pass/fail test"System is reliable""99.9% uptime over 30 days"
Unique IDsNo duplicate IDs across all tablesTwo FR-001 entriesEach ID used exactly once

Error Recovery

  • Incomplete source document: List what is missing (roles, NFR categories, constraints) and ask the user to clarify before proceeding
  • Ambiguous requirement from user: Rewrite it as a measurable requirement and ask the user to confirm the threshold
  • Conflicting requirements: Flag the conflict explicitly (e.g., "FR-003 requires real-time sync but C-002 limits to batch processing") and ask the user to resolve
  • Missing stakeholder roles: Default to generic roles (User, Admin, System) and note them for user review

Workflow

  1. Read the vision document or project brief
  2. Use TodoWrite to create tasks for each requirement type
  3. Write the document header
  4. For functional requirements:
    • Identify user roles
    • Define user stories with clear goals and benefits
    • Assign priorities based on business value
  5. For non-functional requirements:
    • Define measurable quality attributes
    • Categorize by NFR type
    • Ensure requirements are testable
  6. For constraints:
    • Document technical and business limitations
    • Categorize by constraint type
  7. Validate: run every requirement against the quality checks table above
    • No duplicate IDs across all tables
    • All Status columns filled
    • All user stories follow "As a [role], I want [goal] so that [benefit]"
    • All NFRs contain a measurable threshold
  8. Mark todos complete

Use Case Diagram

Instructions

Create or update the PlantUML use case diagram at docs/use_cases.puml based on docs/requirements.md.

DO NOT

  • Create diagrams without reading the requirements first
  • Use non-standard PlantUML syntax
  • Include implementation details in use case names

Template

@startuml Use Cases Overview
left to right direction

actor "User" as user
actor "Administrator" as admin

rectangle "System Name" {
    usecase "UC-001\nDescription" as UC001
    usecase "UC-002\nDescription" as UC002
    usecase "UC-003\nDescription" as UC003
}

admin --> UC001
user --> UC002
user --> UC003

@enduml

Conventions

  • Each use case has a unique id and a description
  • Use Case ID: UC-{3-digit} (UC-001, UC-002, ...)
  • Each use case should trace to at least one functional requirement
  • Add notes sparingly, only where relationships need clarification

Workflow

  1. Read the requirements at docs/requirements.md
  2. Read existing diagram at docs/use_cases.puml (if exists)
  3. Identify actors and use cases from requirements
  4. Create/update the PlantUML use case diagram
  5. Validate the diagram:
    • Each use case traces to at least one functional requirement in docs/requirements.md
    • All actors are connected to at least one use case
    • Use case IDs follow the UC-{3-digit} convention
    • PlantUML syntax is valid (no missing @enduml, proper arrow syntax)

Use Case Specification

Instructions

Create or update use case specification documents for $ARGUMENTS in docs/use_cases/. Each use case describes a complete interaction between an actor and the system to achieve a goal.

DO NOT

  • Write vague or incomplete scenarios
  • Skip numbering steps in the Main Success Scenario
  • Omit alternative flows for error conditions
  • Leave postconditions undefined
  • Mix multiple use cases in one document
  • Use technical implementation details in the flow steps

Template

Use templates/use-case.md as the document structure.

Example Use Case

Use Case: Create Reservation

Overview

Use Case ID: UC-001 Use Case Name: Create Reservation Primary Actor: Front Desk Clerk Goal: Create a new room reservation for a guest Status: Approved

Preconditions

  • Clerk is logged into the system
  • At least one room type is available for the requested dates

Main Success Scenario

  1. Clerk selects "New Reservation" from the menu.
  2. System displays the reservation form.
  3. Clerk enters guest information (name, email, phone).
  4. Clerk selects check-in and check-out dates.
  5. System displays available room types for the selected dates.
  6. Clerk selects a room type.
  7. System calculates the total price.
  8. Clerk confirms the reservation.
  9. System creates the reservation and displays a confirmation number.

Alternative Flows

A1: Guest Already Exists

Trigger: Guest email matches existing record (step 3) Flow:

  1. System displays existing guest information.
  2. Clerk confirms or updates guest details.
  3. Use case continues at step 4.

A2: No Rooms Available

Trigger: No rooms available for selected dates (step 5) Flow:

  1. System displays "No availability" message.
  2. Clerk adjusts dates or cancels operation.
  3. Use case continues at step 4 or ends.

A3: Payment Required

Trigger: Business rule requires deposit (step 8) Flow:

  1. System prompts for payment information.
  2. Clerk enters payment details.
  3. System processes payment.
  4. Use case continues at step 9.

Postconditions

Success Postconditions

  • Reservation is stored in the system with status "Confirmed"
  • Room availability is updated for the reserved dates
  • Confirmation email is sent to the guest

Failure Postconditions

  • No reservation is created
  • Room availability remains unchanged
  • System displays error message to clerk

Business Rules

BR-001: Minimum Stay

Reservations must be for at least one night.

BR-002: Advance Booking Limit

Reservations cannot be made more than 365 days in advance.

BR-003: Deposit Requirement

Reservations of 3 or more nights require a 50% deposit.

Workflow

  1. Read the requirements document and use case diagram
  2. Identify the use case to document
  3. Use TodoWrite to track progress
  4. Write the Overview section with actor and goal
  5. Define preconditions (what must be true before starting)
  6. Write the Main Success Scenario step by step
  7. Identify alternative flows:
    • Error conditions
    • Optional paths
    • Exceptional situations
  8. Define postconditions for both success and failure
  9. Document applicable business rules
  10. Review for completeness and clarity
  11. Mark todo complete

MCP servers 1

Sponsors

Details

Marketplace
martinellich/aiup-marketplace
Source
aiup-core
Category
Community

More from martinellich/aiup-marketplace

All 2