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

```text
$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/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, use the **AskUserQuestion** tool to gather 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 "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

```markdown
| 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:

```markdown
**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

```markdown
## 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](https://www.gov.uk/government/publications/the-sourcing-and-consultancy-playbooks) 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:

```markdown
## 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