Arckit Sow

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}-SOW-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 requirements references, corrected details
   • Major increment (e.g., 1.0 → 2.0): Scope materially changed — new requirement categories, fundamentally different procurement approach, significant scope changes
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 describing what changed from the previous version

Step 1: Construct Document ID

• Document ID: ARC-{PROJECT_ID}-SOW-v{VERSION} (e.g., ARC-001-SOW-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] → "Statement of Work"
• ARC-[PROJECT_ID]-SOW-v[VERSION] → Construct using format from Step 1
• [COMMAND] → "arckit.sow"

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-sow` command | [PENDING] | [PENDING] |

Step 4: Populate Generation Metadata Footer

The footer should be populated with:

**Generated by**: ArcKit `$arckit-sow` 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-SOW-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-sow` command | [PENDING] | [PENDING] |

10. Summarize what you created:

• Key scope items
• Major deliverables
• Suggested timeline
• Next steps (e.g., "Now run $arckit-evaluate to create vendor evaluation framework")

Example Usage

User: $arckit-sow Generate SOW for payment gateway modernization project

You should:

• Find project 001-payment-gateway-modernization
• Read ARC--REQ-.md from that project
• Read architecture principles
• Generate comprehensive SOW:
  • Executive summary with business case
  • Scope: Payment processing, fraud detection, reporting (IN); mobile app (OUT)
  • All requirements from ARC--REQ-.md with IDs
  • Deliverables: HLD, DLD, code, tests, runbooks
  • Timeline: 16 weeks (4 weeks HLD, 4 weeks DLD approval, 8 weeks implementation)
  • Vendor quals: PCI-DSS experience, financial services references
  • Evaluation: 60% technical, 40% cost
  • Contract: Milestone-based payments, 90-day warranty
• CRITICAL - Token Efficiency: Use the Write tool to create projects/001-payment-gateway-modernization/ARC-001-SOW-v1.0.md
  • DO NOT output the full document in your response (this exceeds 32K token limit!)
• Show summary only (see Output Instructions below)

Important Notes

• UK Government procurement: The Sourcing Playbook expects outcome-based specifications, should-cost modelling, social value weighting (minimum 10%), and SME access. See docs/guides/codes-of-practice.md for the full Commercial Playbooks mapping.

• This SOW becomes the legal basis for vendor contracts

• Requirements MUST be complete before generating SOW

• All "MUST" requirements are mandatory; vendors failing to meet them are disqualified

• Include realistic timelines with review gates

• Make acceptance criteria objective and measurable

• Consider adding penalty clauses for SLA violations

• Include provisions for IP ownership and source code escrow

• 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

Output Instructions

CRITICAL - Token Efficiency:

1. Generate SOW Document

Create the comprehensive Statement of Work following the template structure.

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the SOW per-type checks pass. Fix any failures before proceeding.

2. Write Directly to File

Use the Write tool to create projects/[PROJECT]/ARC-{PROJECT_ID}-SOW-v${VERSION}.md with the complete SOW.

DO NOT output the full document in your response. This would exceed token limits.

3. Show Summary Only

After writing the file, show ONLY a concise summary:

## SOW Complete ✅

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

### SOW Summary

**Scope**:
- In Scope: [List key deliverables in scope]
- Out of Scope: [List explicitly excluded items]
- Assumptions: [Number] key assumptions documented

**Requirements**:
- Total Requirements: [Number]
  - Business Requirements: [Number]
  - Functional Requirements: [Number]
  - Non-Functional Requirements: [Number]
  - Data Requirements: [Number]
  - Integration Requirements: [Number]
- Compliance: [List: PCI-DSS, GDPR, HIPAA, etc.]

**Deliverables**:
- Architecture: [e.g., HLD, DLD, ERD]
- Code: [e.g., Source code, unit tests, integration tests]
- Documentation: [e.g., User guides, runbooks, API docs]
- Other: [e.g., Training, data migration]

**Timeline**:
- Total Duration: [Number] weeks
- Phase 1 (HLD): [Number] weeks
- Phase 2 (DLD): [Number] weeks
- Phase 3 (Implementation): [Number] weeks
- Phase 4 (Testing & UAT): [Number] weeks

**Vendor Qualifications**:
- Required Experience: [e.g., 5+ years in financial services]
- Required Certifications: [e.g., PCI-DSS, ISO 27001]
- Team Size: Minimum [Number] FTEs
- References: [Number] client references required

**Evaluation Criteria**:
- Technical Approach: [X]%
- Cost: [X]%
- Experience & References: [X]%
- Timeline & Delivery Plan: [X]%

**Contract Terms**:
- Payment: [e.g., Milestone-based, monthly]
- Warranty: [e.g., 90 days post-delivery]
- SLA Penalties: [Yes/No]
- IP Ownership: [e.g., Client owns all IP]

**UK Government Specific** (if applicable):
- Procurement Route: [e.g., Digital Marketplace, G-Cloud 14]
- Social Value Weighting: [X]%
- Security Clearance: [e.g., SC, DV required]
- Open Source Policy: [Compliance noted]

### What's in the Document

- Executive Summary (business case and objectives)
- Project Scope (in/out/assumptions/dependencies)
- Complete Requirements (all BR, FR, NFR, DR, INT with IDs)
- Deliverables & Acceptance Criteria
- Project Timeline with Review Gates
- Vendor Qualifications & Experience Requirements
- Proposal Evaluation Criteria with Weightings
- Contract Terms & Conditions
- Technical Environment & Constraints
- Appendices (glossary, references, architecture principles)

**Total Length**: [X] pages (ready for RFP release)

### Next Steps

- Review `ARC-{PROJECT_ID}-SOW-v1.0.md` for full SOW document
- Get legal review of contract terms
- Get procurement/finance approval
- Publish to Digital Marketplace (if UK Gov)
- Run `$arckit-evaluate` to create vendor evaluation framework

Statistics to Include:

• Total requirements
• Number of deliverables
• Timeline duration (weeks)
• Number of vendor qualifications
• Number of evaluation criteria
• Page count

Generate the SOW now, write to file using Write tool, and show only the summary above.

Suggested Next Steps

After completing this command, consider running:

• $arckit-evaluate -- Create vendor evaluation framework
• $arckit-dos -- Generate Digital Marketplace DOS opportunity