arckit-sow

name	arckit-sow
description	Generate Statement of Work (SOW) / RFP document for vendor procurement

You are helping an enterprise architect generate a comprehensive Statement of Work (SOW) that will be used as an RFP document for vendor procurement.

User Input

$ARGUMENTS

Instructions

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

1. Identify the target project:

   • Use the ArcKit Project Context (above) to find the project matching the user's input (by name or number)
   • If no match, create a new project:
     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

2. Read existing artifacts from the project context:

   MANDATORY (warn if missing):

   • REQ (Requirements) in projects/{project-dir}/
     • Extract: BR/FR/NFR/INT/DR IDs, priorities, acceptance criteria — source of truth for the SOW
     • If missing: warn user to run $arckit-requirements first
   • PRIN (Architecture Principles, in projects/000-global/)
     • Extract: Technology standards, constraints, compliance requirements for vendor alignment
     • If missing: warn user to run $arckit-principles first

   RECOMMENDED (read if available, note if missing):

   • RSCH / AWSR / AZUR (Technology Research) in projects/{project-dir}/
     • Extract: Vendor landscape, technology decisions, TCO estimates
   • STKE (Stakeholder Analysis) in projects/{project-dir}/
     • Extract: Business drivers, success criteria, evaluation priorities

   OPTIONAL (read if available, skip silently if missing):

   • RISK (Risk Register) in projects/{project-dir}/
     • Extract: Risks requiring vendor mitigation, risk allocation

3. Read the template (with user override support):

   • First, check if .arckit/templates-custom/sow-template.md exists in the project root
   • If found: Read the user's customized template (user override takes precedence)
   • If not found: Read .arckit/templates/sow-template.md (default)

   Tip: Users can customize templates with $arckit-customize sow

4. Read external documents and policies:

   • Read any external documents listed in the project context (external/ files) — extract previous procurement terms, evaluation criteria, contractual clauses, deliverable specifications
   • Read any global policies listed in the project context (000-global/policies/) — extract procurement thresholds, mandatory contractual terms, approved supplier lists, framework agreements
   • Read any enterprise standards in projects/000-global/external/ — extract enterprise procurement templates, contract frameworks, cross-project commercial benchmarks
   • If no external docs exist but they would improve the SoW, ask: "Do you have any previous SoW templates, RFP/ITT documents, or procurement policies? I can read PDFs directly. Place them in projects/{project-dir}/external/ and re-run, or skip."
   • Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

5. Interactive Configuration:

   Before generating the SOW, ask the user for procurement preferences. Skip any question the user has already answered in their arguments.

   Gathering rules (apply to all questions in this section):

   • Ask the most important question first; fill in secondary details from context or reasonable defaults.
   • Maximum 2 rounds of questions. After that, pick the best option from available context.
   • If still ambiguous after 2 rounds, choose the (Recommended) option and note: "I went with [X] — easy to adjust if you prefer [Y]."

   Question 1 — header: Contract, multiSelect: false

   "What contract type should the SOW specify?"

   • Fixed-price (Recommended): Vendor commits to delivering scope for agreed price — lower risk for buyer, requires well-defined requirements
   • Time & Materials: Pay for actual effort — flexible scope, higher cost risk, suited for discovery/R&D
   • Hybrid: Fixed-price for defined deliverables + T&M for change requests — balanced risk sharing

   Question 2 — header: Weighting, multiSelect: false

   "How should vendor proposals be evaluated?"

   • 60% Technical / 40% Cost (Recommended): Standard weighting — prioritizes quality while maintaining cost discipline
   • 70% Technical / 30% Cost: Quality-first — for complex or high-risk projects where technical excellence is critical
   • 50% Technical / 50% Cost: Balanced — for commodity procurements with well-understood requirements
   • 80% Technical / 20% Cost: Innovation-focused — for R&D, AI, or cutting-edge technology projects

   Apply the user's selections: the contract type determines the pricing structure, payment terms, and risk allocation sections. The evaluation weighting is used in the Evaluation Criteria section and scoring framework.

6. Generate comprehensive SOW with these sections:

   Executive Summary:

   • Project overview and objectives
   • Expected business outcomes
   • Key success criteria

   Scope of Work:

   • What's in scope (explicitly list)
   • What's out of scope (explicitly list)
   • Assumptions and constraints
   • Dependencies

   Requirements:

   • Import from ARC--REQ-.md
   • Organise by Business, Functional, Non-Functional, Integration
   • Clearly mark which are MUST vs SHOULD vs MAY
   • Reference requirement IDs (BR-001, FR-001, etc.)

   Deliverables:

   • High-Level Design (HLD) document + diagrams
   • Detailed Design (DLD) document
   • Source code and documentation
   • Test plans and test results
   • Deployment runbooks
   • Training materials
   • Warranty and support terms

   Timeline and Milestones:

   • Suggested project phases
   • Key milestones and decision gates
   • Review and approval gates (HLD review, DLD review)

   Vendor Qualifications:

   • Required certifications
   • Team experience requirements
   • Reference requirements
   • Financial stability requirements

   Proposal Requirements:

   • Technical approach and methodology
   • Team composition and CVs
   • Project timeline with milestones
   • Pricing breakdown (fixed-price or T&M)
   • Risk mitigation approach
   • References

   Evaluation Criteria:

   • How proposals will be scored
   • Weighting for technical vs cost
   • Mandatory qualifications (pass/fail)
   • Reference to evaluation-criteria-template.md

   Contract Terms:

   • Payment terms and milestones
   • Acceptance criteria
   • Change management process
   • Intellectual property rights
   • Warranties and support
   • Termination clauses

7. Ensure alignment:

   • Cross-reference architecture principles from any ARC-000-PRIN-*.md file in projects/000-global/
   • Ensure all requirements from the requirements document are included
   • Add validation gates that align with principles

8. Make it RFP-ready:

   • Use formal language appropriate for legal review
   • Be specific and unambiguous
   • Include submission instructions and deadline
   • Specify format requirements (e.g., "proposals must be PDF")

9. Write the output:

   • Write to projects/{project-dir}/ARC-{PROJECT_ID}-SOW-v${VERSION}.md
   • Use the exact template structure

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 ${default_classification}; if unavailable, use "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 5 (session default)"]
**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