Arckit Requirements

1. Use Glob to list projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)
2. Calculate the next number (zero-padded to 3 digits, e.g., 002)
3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
4. Use the Write tool to create projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automatically
5. Also create projects/{NNN}-{slug}/external/README.md with a note to place external reference documents here
6. Set PROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory path

CRITICAL - Auto-Populate Document Control Fields:

Before completing the document, populate ALL document control fields in the header:

Step 0: Detect Version

Before generating the document ID, check if a previous version exists:

1. Look for existing ARC-{PROJECT_ID}-REQ-v*.md files in the project directory
2. If no existing file: Use VERSION="1.0"
3. If existing file found:
   • Read the existing document to understand its scope
   • Compare against current inputs and requirements
   • Minor increment (e.g., 1.0 → 1.1): Scope unchanged — refreshed content, updated details, corrections
   • Major increment (e.g., 1.0 → 2.0): Scope materially changed — new requirement categories, removed categories, significant new requirements added
4. Use the determined version for document ID, filename, Document Control, and Revision History
5. For v1.1+/v2.0+: Add a Revision History entry

Step 1: Construct Document ID

• Document ID: ARC-{PROJECT_ID}-REQ-v{VERSION} (e.g., ARC-001-REQ-v1.0)

Step 2: Populate Required Fields

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → Determined version from Step 0
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "Business and Technical Requirements"
• ARC-[PROJECT_ID]-REQ-v[VERSION] → Construct using format from Step 1
• [COMMAND] → "arckit.requirements"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] → Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] → Document owner (prompt user if not in metadata)
• [CLASSIFICATION] → Default to "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

Calculated fields:

• [YYYY-MM-DD] for Review Date → Current date + 30 days (requirements, research, risks)
• [YYYY-MM-DD] for Review Date → Phase gate dates (Alpha/Beta/Live for compliance docs)

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] → [PENDING]
• [APPROVER_NAME] → [PENDING]
• [DISTRIBUTION_LIST] → Default to "Project Team, Architecture Team" or [PENDING]

Step 3: Populate Revision History

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-requirements` command | [PENDING] | [PENDING] |

Step 4: Populate Generation Metadata Footer

The footer should be populated with:

**Generated by**: ArcKit `$arckit-requirements` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "claude-sonnet-4-5-20250929"]
**Generation Context**: [Brief note about source documents used]

Example Fully Populated Document Control Section

## Document Control

| Field | Value |
|-------|-------|
| **Document ID** | ARC-001-REQ-v1.0 |
| **Document Type** | {Document purpose} |
| **Project** | Windows 10 to Windows 11 Migration (Project 001) |
| **Classification** | OFFICIAL-SENSITIVE |
| **Status** | DRAFT |
| **Version** | 1.0 |
| **Created Date** | 2025-10-29 |
| **Last Modified** | 2025-10-29 |
| **Review Date** | 2025-11-30 |
| **Owner** | John Smith (Business Analyst) |
| **Reviewed By** | [PENDING] |
| **Approved By** | [PENDING] |
| **Distribution** | PM Team, Architecture Team, Dev Team |

## Revision History

| Version | Date | Author | Changes | Approved By | Approval Date |
|---------|------|--------|---------|-------------|---------------|
| 1.0 | 2025-10-29 | ArcKit AI | Initial creation from `$arckit-requirements` command | [PENDING] | [PENDING] |

10. Show summary only (NOT the full document):

After writing the file with Write tool, show ONLY this summary:

## Requirements Complete ✅

**Project**: [Project Name]
**File Created**: `projects/[PROJECT]/ARC-{PROJECT_ID}-REQ-v1.0.md`

### Requirements Summary

**Total Requirements**: [Number]
- Business Requirements (BR-xxx): [Number]
- Functional Requirements (FR-xxx): [Number]
- Non-Functional Requirements (NFR-xxx): [Number]
  - Performance (NFR-P-xxx): [Number]
  - Security (NFR-SEC-xxx): [Number]
  - Scalability (NFR-S-xxx): [Number]
  - Availability (NFR-A-xxx): [Number]
  - Compliance (NFR-C-xxx): [Number]
- Data Requirements (DR-xxx): [Number]
- Integration Requirements (INT-xxx): [Number]

**Requirement Conflicts**: [Number] conflicts identified and resolved
- [Brief summary of key conflicts and resolutions]
- [Which stakeholders won/lost in conflicts]

**Compliance Requirements**:
- [List key compliance frameworks: PCI-DSS, GDPR, HIPAA, etc.]

**Key Gaps/TBDs**:
- [List any major gaps that need follow-up]

### What's in the Document

- Business Requirements with measurable success criteria
- Functional Requirements organized by user journey
- Non-Functional Requirements with specific targets
- Data Requirements with GDPR considerations
- Integration Requirements with third-party systems
- Acceptance Criteria for each requirement
- Requirements Traceability Matrix
- Requirement Conflicts & Resolutions

### Next Steps

- Review `ARC-{PROJECT_ID}-REQ-v1.0.md` for full details
- [If DR-xxx exist]: Run `$arckit-data-model` to create comprehensive data model
- [If no DR-xxx]: Run `$arckit-research` to research technology options

Example Usage

User: $arckit-requirements Create requirements for a payment gateway modernization project

You should:

• Check for architecture principles
• Create project "payment-gateway-modernization" (gets number 001)
• Generate comprehensive requirements:
  • Business: Cost savings, improved conversion, reduced downtime
  • Functional: Payment processing, refunds, fraud detection, reporting
  • NFR: PCI-DSS compliance, 99.99% uptime, <2s response time, encryption
  • Integration: CRM, accounting system, fraud service
  • Data: Transaction records, PII handling, 7-year retention
• Write to projects/001-payment-gateway-modernization/ARC-001-REQ-v1.0.md
• Confirm completion with summary

Important Notes

• Requirements drive everything: SOW, vendor evaluation, design reviews, testing
• Be specific and measurable (avoid "fast", use "< 2 seconds")
• Include WHY (rationale) not just WHAT
• Make acceptance criteria testable
• Flag compliance requirements clearly (PCI-DSS, HIPAA, SOX, GDPR, etc.)
• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji

Suggested Next Steps

After completing this command, consider running:

• $arckit-data-model -- Create data model from data requirements (when DR-xxx data requirements were generated)
• $arckit-research -- Research technology options
• $arckit-risk -- Create risk register from requirements
• $arckit-dpia -- Assess data protection impact