
aiup-core
AI Unified Process - stack-agnostic core methodology (requirements, entity model, use cases)
- GitHub stars
- 37
Install
/plugin install aiup-core@aiup-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add martinellich/aiup-marketplace.
Contents
Discovered from sourceSkills 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.
| Attribute | Description | Data Type | Length/Precision | Validation Rules |
|---|---|---|---|---|
| id | ... | Long | 19 | Primary Key, Sequence |
| ... | ... | ... | ... | ... |
Required Format for Each Entity
Every entity MUST have:
- A ### heading with ENTITY_NAME
- One sentence description
- An attribute table with exactly 5 columns
Example Entity
ROOM_TYPE
Defines categories of rooms with shared characteristics.
| Attribute | Description | Data Type | Length/Precision | Validation Rules |
|---|---|---|---|---|
| id | Unique identifier | Long | 19 | Primary Key, Sequence |
| name | Name of the room type | String | 50 | Not Null, Unique |
| description | Detailed description | String | 500 | Optional |
| capacity | Maximum number of guests | Integer | 10 | Not Null, Min: 1, Max: 10 |
| price | Price per night in CHF | Decimal | 10,2 | Not 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 Type | Validation Rules Value |
|---|---|
| Primary key | Primary Key, Sequence |
| Required field | Not Null |
| Unique field | Not Null, Unique |
| Foreign key | Not Null, Foreign Key (TABLE.id) |
| Optional field | Optional |
| With range | Not Null, Min: X, Max: Y |
| With values | Not Null, Values: A, B, C |
| Not Null, Format: Email |
Data Types Reference
| Data Type | Length/Precision | Usage |
|---|---|---|
| Long | 19 | IDs, foreign keys |
| String | varies (50-500) | Text fields |
| Integer | 10 | Whole numbers |
| Decimal | 10,2 | Currency, percentages |
| Boolean | 1 | True/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
- Read the requirements document
- Use TodoWrite to create a task for each entity
- Write the document header and ER diagram (relationships only)
- For each entity:
- Write ### heading
- Write one sentence description
- Write attribute table with 5 columns
- Add constraints if needed
- Mark todo complete
- 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].
| ID | Title | User Story | Priority | Status |
|---|---|---|---|---|
| FR-001 | Create Task | As a project manager, I want to create tasks so that I can track work items. | High | Open |
| FR-002 | Assign Task | As a project manager, I want to assign tasks to team members so that work is distributed. | High | Open |
| FR-003 | Filter Tasks | As a team member, I want to filter tasks by status so that I can focus on relevant items. | Medium | Open |
Non-Functional Requirements (NFR)
Define quality attributes. Must be measurable.
| ID | Title | Requirement | Category | Priority | Status |
|---|---|---|---|---|---|
| NFR-001 | Response Time | All page loads must complete within 2 seconds. | Performance | High | Open |
| NFR-002 | Availability | System must maintain 99.9% uptime during business hours. | Availability | High | Open |
| NFR-003 | Concurrent Users | System must support 100 concurrent users without degradation. | Scalability | Medium | Open |
| NFR-004 | Data Encryption | All data in transit must use TLS 1.3 encryption. | Security | High | Open |
Constraints (C)
Define limitations and boundaries imposed on the solution.
| ID | Title | Constraint | Category | Priority | Status |
|---|---|---|---|---|---|
| C-001 | Runtime Platform | Backend must run on Java 21 LTS. | Technical | High | Open |
| C-002 | Database Platform | System must use PostgreSQL 16. | Technical | High | Open |
| C-003 | Browser Support | UI must support Chrome, Firefox, and Safari (latest 2 versions). | Technical | High | Open |
| C-004 | Budget Limit | Total development cost must not exceed $50,000. | Business | High | Open |
| C-005 | Deadline | System must be production-ready by Q2 2025. | Schedule | High | Open |
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:
| Check | Rule | Bad Example | Good Example |
|---|---|---|---|
| Measurable | NFRs must have a number or threshold | "System should be fast" | "Pages load within 2 seconds" |
| Singular | One requirement per row | "System must log in and export data" | Split into FR-001 and FR-002 |
| Unambiguous | No subjective terms | "User-friendly interface" | "WCAG 2.1 AA compliant" |
| Testable | Can write a pass/fail test | "System is reliable" | "99.9% uptime over 30 days" |
| Unique IDs | No duplicate IDs across all tables | Two FR-001 entries | Each 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
- Read the vision document or project brief
- Use TodoWrite to create tasks for each requirement type
- Write the document header
- For functional requirements:
- Identify user roles
- Define user stories with clear goals and benefits
- Assign priorities based on business value
- For non-functional requirements:
- Define measurable quality attributes
- Categorize by NFR type
- Ensure requirements are testable
- For constraints:
- Document technical and business limitations
- Categorize by constraint type
- 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
- 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
- Read the requirements at
docs/requirements.md - Read existing diagram at
docs/use_cases.puml(if exists) - Identify actors and use cases from requirements
- Create/update the PlantUML use case diagram
- 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)
- Each use case traces to at least one functional requirement in
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
- Clerk selects "New Reservation" from the menu.
- System displays the reservation form.
- Clerk enters guest information (name, email, phone).
- Clerk selects check-in and check-out dates.
- System displays available room types for the selected dates.
- Clerk selects a room type.
- System calculates the total price.
- Clerk confirms the reservation.
- System creates the reservation and displays a confirmation number.
Alternative Flows
A1: Guest Already Exists
Trigger: Guest email matches existing record (step 3) Flow:
- System displays existing guest information.
- Clerk confirms or updates guest details.
- Use case continues at step 4.
A2: No Rooms Available
Trigger: No rooms available for selected dates (step 5) Flow:
- System displays "No availability" message.
- Clerk adjusts dates or cancels operation.
- Use case continues at step 4 or ends.
A3: Payment Required
Trigger: Business rule requires deposit (step 8) Flow:
- System prompts for payment information.
- Clerk enters payment details.
- System processes payment.
- 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
- Read the requirements document and use case diagram
- Identify the use case to document
- Use TodoWrite to track progress
- Write the Overview section with actor and goal
- Define preconditions (what must be true before starting)
- Write the Main Success Scenario step by step
- Identify alternative flows:
- Error conditions
- Optional paths
- Exceptional situations
- Define postconditions for both success and failure
- Document applicable business rules
- Review for completeness and clarity
- Mark todo complete
MCP servers 1
Sponsors
Details
- Marketplace
- martinellich/aiup-marketplace
- Source
- aiup-core
- Category
- Community