tractorjuice/arckit-dos

You are helping an enterprise architect prepare Digital Outcomes and Specialists (DOS) procurement documentation for the UK Digital Marketplace.

User Input

$ARGUMENTS

Context

Digital Outcomes and Specialists (DOS) is the UK Digital Marketplace framework for:

• Custom software development
• Hiring developers, architects, designers, and technical specialists
• Delivering specific digital project outcomes

This command generates DOS-compliant procurement documentation from your existing arc-kit project requirements.

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.

0. Read the Template

Read the template (with user override support):

• First, check if .arckit/templates-custom/dos-requirements-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/dos-requirements-template.md (default)

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

1. Read existing artifacts from the project context

MANDATORY (warn if missing):

• PRIN (Architecture Principles, in 000-global) — Extract: technology standards, governance constraints for vendor proposals
  • If missing: ERROR — run $arckit-principles first to define governance standards
• REQ (Requirements) — Extract: BR/FR/NFR/INT/DR IDs, priorities, acceptance criteria — source of truth for DOS
  • If missing: ERROR — run $arckit-requirements first to define project needs

RECOMMENDED (read if available, note if missing):

• STKE (Stakeholder Analysis) — Extract: user personas, business drivers, evaluation priorities
  • If missing: WARN — consider running $arckit-stakeholders to understand stakeholder priorities
• RSCH/AWRS/AZRS (Technology Research) — Extract: technology decisions informing essential skills requirements

OPTIONAL (read if available, skip silently):

• SOW (Statement of Work) — Extract: additional procurement context, scope definitions
• RISK (Risk Register) — Extract: risks requiring vendor mitigation, compliance requirements

1b. Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract team capability evidence, previous submission scores, buyer requirements, evaluation feedback
• Read any enterprise standards in projects/000-global/external/ — extract organization-wide procurement templates, DOS framework guidance, approved supplier capabilities
• If no external DOS docs exist but they would improve the submission, ask: "Do you have any contractor CVs, previous DOS submissions, or buyer requirement documents? 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.

Gathering rules (apply to all user questions in this command):

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

2. 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
• Parse user input for additional context (budget, timeline, specific skills)

---

CRITICAL - Auto-Populate Document Control Fields:

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

Construct Document ID:

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

Populate Required Fields:

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → "1.0" (or increment if previous version exists)
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "DOS Procurement Requirements"
• ARC-[PROJECT_ID]-DOS-v[VERSION] → Construct using format above
• [COMMAND] → "arckit.dos"

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 ${user_config.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

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

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

Populate Revision History:

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

Populate Generation Metadata Footer:

The footer should be populated with:

**Generated by**: ArcKit `$arckit-dos` 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]

---

3. Generate DOS Procurement Documentation

Create directory: projects/[project]/procurement/

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

Generate projects/[project]/procurement/ARC-{PROJECT_ID}-DOS-v1.0.md:

# UK Digital Marketplace: Digital Outcomes and Specialists

**Framework**: Digital Outcomes and Specialists (DOS)
**Procurement Type**: [Digital Outcome / Digital Specialists / Outcome + Specialists]
**Generated**: [DATE]
**Project**: [PROJECT_NAME]
**Project ID**: [PROJECT_ID]
**Requirements Source**: [Link to ARC-*-REQ-*.md]

---

## 1. Executive Summary

### 1.1 Procurement Overview

[1-2 paragraph summary extracted from ARC-*-REQ-*.md Business Requirements section - describe what needs to be delivered and why]

### 1.2 Strategic Alignment

**Architecture Principles**:
[Reference relevant principles from ARC-000-PRIN-*.md that constrain this procurement]

**Stakeholder Priorities** (if ARC-*-STKE-*.md exists):
[List top 3 stakeholder drivers/goals this addresses with IDs: D-001, G-001, etc.]

### 1.3 Expected Outcomes

[Extract from ARC-*-REQ-*.md Business Requirements (BR-xxx) - the measurable outcomes]

---

## 2. Digital Outcome Description

[Describe what vendor must deliver - the complete deliverable or specific outcome]

**What Success Looks Like**:

[Extract success criteria from ARC-*-REQ-*.md - ensure technology-agnostic]
- [Outcome 1 with measurable metric]
- [Outcome 2 with measurable metric]
- [Outcome 3 with measurable metric]

**Compliance with Architecture Principles**:
- [Principle Name]: [How outcome must comply]
- [Principle Name]: [How outcome must comply]

---

## 3. Essential Skills and Experience

[Extract from ARC-*-REQ-*.md - what capabilities are absolutely required]

### 3.1 Technical Capabilities (MUST Have)

From Functional Requirements (FR-xxx):
- **[Capability Area 1]**: [Skill needed to deliver FR-xxx requirements]
- **[Capability Area 2]**: [Skill needed to deliver FR-xxx requirements]
- **[Capability Area 3]**: [Skill needed to deliver FR-xxx requirements]

### 3.2 Non-Functional Expertise (MUST Have)

From Non-Functional Requirements (NFR-xxx):
- **Security**: [Skills for NFR-S-xxx requirements, reference security principles]
- **Performance**: [Skills for NFR-P-xxx requirements]
- **Compliance**: [Skills for NFR-C-xxx requirements, reference compliance principles]
- **Integration**: [Skills for INT-xxx requirements]

### 3.3 Architecture Governance (MUST Have)

From ARC-000-PRIN-*.md:
- **[Principle Category]**: Experience with [specific technology/approach mandated by principles]
- **Design Reviews**: Experience with HLD/DLD review processes
- **Documentation**: Ability to produce architecture diagrams (Mermaid, C4)
- **Traceability**: Experience maintaining requirements traceability throughout delivery

---

## 4. Desirable Skills and Experience

[Nice-to-have skills that would enhance delivery]

From SHOULD requirements:
- [Desirable skill 1]
- [Desirable skill 2]
- [Desirable skill 3]

---

## 5. User Needs and Scenarios

[Extract user personas and scenarios from ARC-*-REQ-*.md to help vendors understand context]

**User Personas**:
[List personas from Functional Requirements section]

**Key User Journeys**:
1. [Journey 1 summary]
2. [Journey 2 summary]
3. [Journey 3 summary]

---

## 6. Requirements Summary

### 6.1 Business Requirements

[Extract all BR-xxx from ARC-*-REQ-*.md with IDs and priority]

| ID | Requirement | Priority | Acceptance Criteria |
|----|-------------|----------|---------------------|
| BR-001 | [requirement] | MUST | [criteria] |
| BR-002 | [requirement] | SHOULD | [criteria] |

### 6.2 Functional Requirements

[Extract all FR-xxx from ARC-*-REQ-*.md - group by capability area]

**[Capability Area 1]**:
- **FR-001** (MUST): [requirement] - [acceptance criteria]
- **FR-002** (MUST): [requirement] - [acceptance criteria]

**[Capability Area 2]**:
- **FR-003** (MUST): [requirement] - [acceptance criteria]

### 6.3 Non-Functional Requirements

[Extract all NFR-xxx from ARC-*-REQ-*.md - organize by category]

**Performance (NFR-P-xxx)**:
- [requirement with measurable targets]

**Security (NFR-S-xxx)**:
- [requirement with compliance references]

**Compliance (NFR-C-xxx)**:
- [requirement with standards/regulations]

**Scalability (NFR-SC-xxx)**:
- [requirement with capacity targets]

**Reliability (NFR-R-xxx)**:
- [requirement with uptime/availability targets]

### 6.4 Integration Requirements

[Extract all INT-xxx from ARC-*-REQ-*.md]

**Upstream Systems**:
- INT-xxx: [system and integration method]

**Downstream Systems**:
- INT-xxx: [system and integration method]

**Data Requirements (DR-xxx)**:
- [Extract any DR-xxx data requirements relevant to integration]

---

## 7. Scope and Boundaries

### 7.1 In Scope

[Extract from ARC-*-REQ-*.md scope section OR infer from MUST requirements]
- [Scope item 1]
- [Scope item 2]
- [Scope item 3]

### 7.2 Out of Scope

[Extract from ARC-*-REQ-*.md OR infer from explicitly excluded items]
- [Exclusion 1]
- [Exclusion 2]

---

## 8. Constraints and Dependencies

### 8.1 Architecture Constraints

[From ARC-000-PRIN-*.md - what vendors MUST comply with]
- **[Constraint Type]**: [Specific constraint from principles]
- **[Constraint Type]**: [Specific constraint from principles]

### 8.2 Technical Dependencies

[From ARC-*-REQ-*.md dependencies section or INT-xxx]
- [Dependency 1]
- [Dependency 2]

### 8.3 Timelines

[If specified in user input or requirements]
- **Project Duration**: [timeline]
- **Key Milestones**: [milestones]
- **Critical Deadlines**: [deadlines if any]

---

## 9. Project Governance

### 9.1 Architecture Review Gates

**Mandatory Reviews**:
- ✅ **High-Level Design (HLD) Review** - before detailed design
- ✅ **Detailed Design (DLD) Review** - before implementation
- ✅ **Code Review** - ongoing during implementation
- ✅ **Security Review** - before go-live
- ✅ **Compliance Review** - before go-live

Reference: Run `$arckit-hld-review` and `$arckit-dld-review` for formal review processes

### 9.2 Compliance Requirements

[From ARC-000-PRIN-*.md and NFR-C-xxx requirements]
- [Compliance requirement 1]
- [Compliance requirement 2]

### 9.3 Requirements Traceability

Vendor must maintain requirements traceability throughout delivery:
- Requirements → High-Level Design
- Requirements → Detailed Design
- Requirements → Test Cases
- Requirements → Deliverables

Reference: `$arckit-traceability` for traceability matrix generation and validation

---

## 10. Budget Considerations

[If provided by user - otherwise mark as TBD]

**Estimated Budget**: [budget range]

**Payment Structure**: [milestone-based / time & materials / fixed price]

**Contract Length**: [duration]

---

## 11. Evaluation Criteria

Suppliers will be evaluated according to Digital Marketplace guidelines:

### 11.1 Technical Capability (40%)

**Essential Criteria** (Pass/Fail):
- ✅ Meets ALL MUST requirements (from section 6)
- ✅ Meets ALL essential skills (from section 3.1-3.3)
- ✅ Demonstrates architecture governance experience
- ✅ Demonstrates requirements traceability capabilities

**Scoring Criteria**:
- **Technical Approach** (20%): Quality of proposed solution, alignment with architecture principles
- **Evidence of Delivery** (10%): Similar projects delivered, relevant domain experience
- **Understanding of Requirements** (10%): Depth of requirements understanding, risk identification

### 11.2 Team Experience and Composition (30%)

- **Team Skills Match** (15%): Coverage of essential + desirable skills
- **Track Record** (10%): Relevant project experience, client references, success stories
- **Team Structure** (5%): Appropriate roles, seniority levels, availability commitment

### 11.3 Quality Assurance (20%)

- **Testing Approach** (10%): Test coverage strategy, automation, non-functional testing
- **Compliance & Security** (5%): Security testing approach, compliance validation methods
- **Documentation** (5%): Quality of design docs, runbooks, training materials, handover plan

### 11.4 Value for Money (10%)

- **Cost Breakdown** (5%): Transparency, justification, flexibility, no hidden costs
- **Risk Mitigation** (5%): Approach to project risks, contingency planning, issue management

---

## 12. Deliverables

### 12.1 Architecture & Design

- ✅ **High-Level Design (HLD)** document with Mermaid diagrams
- ✅ **Detailed Design (DLD)** document
- ✅ **Data model** and schemas (if applicable)
- ✅ **API contracts** and specifications (if applicable)
- ✅ **Security design** documentation
- ✅ **Integration design** documentation (for INT-xxx requirements)

Reference: Generate with `$arckit-diagram`, `$arckit-data-model`

### 12.2 Implementation

- ✅ **Source code** (following architecture principles)
- ✅ **Configuration** and deployment scripts
- ✅ **Database migration** scripts (if applicable)
- ✅ **Infrastructure as Code** (if applicable)

### 12.3 Testing & Quality

- ✅ **Test plans** and test cases (linked to requirements)
- ✅ **Test results** and coverage reports
- ✅ **Performance test results** (NFR-P-xxx validation)
- ✅ **Security test results** (NFR-S-xxx validation)
- ✅ **Compliance evidence** (NFR-C-xxx validation)

### 12.4 Documentation

- ✅ **User documentation** and guides
- ✅ **Administrator documentation**
- ✅ **Deployment runbooks**
- ✅ **Training materials**
- ✅ **Requirements traceability matrix** (Requirements → Design → Tests → Code)
- ✅ **Handover documentation**

### 12.5 Support & Warranty

- ✅ [Warranty period and terms]
- ✅ [Support arrangements and SLAs]
- ✅ [Knowledge transfer plan]
- ✅ [Defect management process]

---

## 13. Proposal Submission Requirements

Vendors must provide:

1. **Technical Proposal**
   - Proposed solution architecture (aligned with ARC-000-PRIN-*.md)
   - Approach to each requirement category (BR, FR, NFR, INT, DR)
   - Risk assessment and mitigation strategy
   - Quality assurance approach
   - Compliance and security approach

2. **Team Proposal**
   - Team composition and roles
   - CVs demonstrating essential skills
   - Availability and commitment (% allocation)
   - Client references (minimum 2 from similar projects)
   - Escalation path and governance structure

3. **Project Plan**
   - Detailed timeline with milestones
   - Resource allocation plan
   - Architecture review gates schedule (HLD, DLD, etc.)
   - Delivery roadmap with dependencies
   - Risk management plan

4. **Commercial Proposal**
   - Detailed cost breakdown by role/phase
   - Payment terms and milestones
   - Assumptions and exclusions
   - Contract terms
   - Change request process

---

## 14. Next Steps

### 14.1 For Procurement Team

2. **Review & Refine**: Validate this document with stakeholders
3. **Budget Approval**: Obtain budget sign-off before publishing
4. **Publish on Digital Marketplace**:
   - Go to: https://www.digitalmarketplace.service.gov.uk/
   - Select "Digital Outcomes and Specialists"
   - Post requirements (publicly visible)
   - Set closing date for proposals
5. **Answer Supplier Questions**: Via Digital Marketplace platform (visible to all)
6. **Evaluate Proposals**: Using criteria in Section 11
7. **Conduct Assessments**: Interview/technical assessment for shortlisted suppliers
8. **Award Contract**: To highest-scoring supplier
9. **Publish Award Details**: On Contracts Finder (legal requirement)

### 14.2 For Architecture Team

2. **Prepare Review Frameworks**:
   - Run `$arckit-hld-review` to set up HLD review process
   - Run `$arckit-dld-review` to set up DLD review process
   - Prepare evaluation scorecards based on Section 11 criteria
3. **Establish Governance**:
   - Set up architecture review board
   - Define review gates and approval process
   - Schedule regular checkpoints with vendor
4. **Traceability Setup**:
   - Run `$arckit-traceability` to establish tracking framework
   - Define traceability requirements for vendor

---

## 15. Resources and References

### 15.1 Digital Marketplace Guidance

- **Sourcing Playbook**: https://www.gov.uk/government/publications/the-sourcing-and-consultancy-playbooks (market assessment, should-cost modelling, outcome-based specs, social value)
- **DDaT Playbook**: https://www.gov.uk/service-manual (open standards, interoperability, modular contracting)
- **Codes of Practice guide**: See `docs/guides/codes-of-practice.md` for the full Rainbow of Books mapping
- **Digital Marketplace**: https://www.digitalmarketplace.service.gov.uk/
- **DOS Buyers Guide**: https://www.gov.uk/guidance/digital-outcomes-and-specialists-buyers-guide
- **General Buying Guide**: https://www.gov.uk/guidance/buying-and-selling-on-the-digital-marketplace
- **Contracts Finder**: https://www.gov.uk/contracts-finder

### 15.2 Project Documents

- **Requirements**: projects/[project]/ARC-*-REQ-v*.md
- **Architecture Principles**: projects/000-global/ARC-000-PRIN-*.md
- **Stakeholder Analysis**: projects/[project]/ARC-*-STKE-v*.md (if exists)
- **General RFP/SOW**: projects/[project]/ARC-*-SOW-v*.md (if exists)

### 15.3 Arc-kit Commands for Vendor Management

- **`$arckit-evaluate`**: Create vendor evaluation framework and scoring
- **`$arckit-hld-review`**: High-Level Design review process for vendor deliverables
- **`$arckit-dld-review`**: Detailed Design review process for vendor deliverables
- **`$arckit-traceability`**: Requirements traceability matrix validation

---

## 16. Important Compliance Notes

**Audit Trail**:
- ✅ All procurement decisions must be documented and auditable
- ✅ Evaluation scoring must be recorded with justification
- ✅ Supplier questions and answers must be visible to all bidders
- ✅ Changes to requirements must be published to all suppliers

**GDS Approval**:
- ⚠️ New or redesigned services may require formal GDS approval
- ⚠️ Check if spend control process applies to your organisation
- ⚠️ Consult with digital/technology leadership before publishing

**Transparency**:
- ✅ Requirements are published publicly on Digital Marketplace
- ✅ Evaluation criteria must be published before receiving proposals
- ✅ Award details must be published on Contracts Finder after completion

**Fair Competition**:
- ✅ All suppliers have equal access to information
- ✅ No preferential treatment during Q&A
- ✅ Evaluation based solely on published criteria
- ✅ No changes to requirements after publishing (unless necessary and communicated to all)

4. Quality Validation

Before finalizing, validate output:

• ✅ All requirements from ARC--REQ-.md are included with IDs
• ✅ Architecture principles are referenced and enforced
• ✅ Stakeholder priorities are reflected (if available)
• ✅ Success criteria are measurable and technology-agnostic
• ✅ Evaluation criteria are fair and transparent
• ✅ Links to gov.uk guidance are correct
• ✅ Traceability to requirement IDs maintained (BR-xxx, FR-xxx, NFR-xxx, INT-xxx, DR-xxx)
• ✅ No implementation details leaked (no specific frameworks, languages, products)

5. Report Completion

Output to user:

✅ Generated DOS procurement documentation for [PROJECT_NAME]

Framework: Digital Outcomes and Specialists (DOS)
Document: projects/[project]/procurement/ARC-{PROJECT_ID}-DOS-v1.0.md

Integration Summary:
- ✅ Requirements extracted from ARC-*-REQ-*.md
- ✅ Architecture principles enforced
- [✅/⚠️] Stakeholder priorities included (ARC-*-STKE-*.md)
- [✅/⚠️] Cross-referenced with existing SOW (ARC-*-SOW-*.md)

Document Sections:
- ✅ Executive Summary (strategic alignment)
- ✅ Digital Outcome Description (what vendor delivers)
- ✅ Essential Skills (MUST have - from FR/NFR/INT)
- ✅ Desirable Skills (SHOULD have)
- ✅ Requirements Summary (all BR/FR/NFR/INT/DR)
- ✅ Scope & Boundaries
- ✅ Evaluation Criteria (40% Technical, 30% Team, 20% Quality, 10% Value)
- ✅ Deliverables (HLD, DLD, code, tests, docs)
- ✅ Governance (review gates, traceability)

Next Steps:
1. Review generated documentation with procurement and stakeholder teams
2. Add budget details if not already specified
3. Obtain formal approval for procurement
4. Publish on Digital Marketplace: https://www.digitalmarketplace.service.gov.uk/
5. Follow DOS buyers guide: https://www.gov.uk/guidance/digital-outcomes-and-specialists-buyers-guide

Related Arc-kit Commands:
- $arckit-evaluate - Create vendor evaluation framework after receiving proposals
- $arckit-hld-review - Set up HLD review process for vendor deliverables
- $arckit-dld-review - Set up DLD review process for vendor deliverables
- $arckit-traceability - Validate requirements traceability with vendor

Important: Maintain audit trail of all procurement decisions per Digital Marketplace requirements.

Key Principles

2. Requirements First: Always pull from ARC--REQ-.md - don't invent new requirements
3. Principle Enforcement: Ensure architecture principles constrain vendor proposals
4. Stakeholder Alignment: Reflect stakeholder priorities in evaluation criteria
5. Technology-Agnostic: Remove all implementation details from procurement docs
6. Traceability: Maintain requirement IDs (BR-xxx, FR-xxx, NFR-xxx, INT-xxx, DR-xxx) throughout
7. Audit-Ready: Structure supports Digital Marketplace audit requirements
8. Gov.uk Aligned: Use official terminology and link to authoritative guidance
9. DOS-Focused: This is ONLY for custom development - no G-Cloud content

Error Handling

• No principles: ERROR "Run $arckit-principles first - governance standards required"
• No requirements: ERROR "Run $arckit-requirements first - nothing to procure"
• No project: Suggest the user run $arckit-init or provide a project name to create one
• Wrong framework: If user mentions G-Cloud or cloud services, suggest $arckit-gcloud-search instead

Important Notes

• 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