arckit-dos

name	arckit-dos
description	Generate Digital Outcomes and Specialists (DOS) procurement documentation for UK Digital Marketplace

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)
• Then read .arckit/templates/_partials/RENDERING.md and resolve the <!-- DOC-CONTROL-HEADER --> marker in the template before writing. Do not hand-write the Document Control table: the partial RENDERING.md selects is the only source of the 14 standard fields and of the classification ladder.

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 → comes from the resolved Document Control header, not from a placeholder. _partials/RENDERING.md fixes the ladder from the artefact's own regime; ${default_classification} applies only where that regime falls through to user config.

Calculated fields:

• [YYYY-MM-DD] for Next 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 5 (session default)"]
**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]
- : [Skills for NFR-P-xxx requirements]
- : [Skills for NFR-C-xxx requirements, reference compliance principles]
- : [Skills for INT-xxx requirements]

### 3.3 Architecture Governance (MUST Have)

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

---



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

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

---



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

:
[List personas from Functional Requirements section]

:
 [Journey 1 summary]
 [Journey 2 summary]
 [Journey 3 summary]

---





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

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



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

:
  (MUST): [requirement] - [acceptance criteria]
  (MUST): [requirement] - [acceptance criteria]

:
  (MUST): [requirement] - [acceptance criteria]



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

:
 [requirement with measurable targets]

:
 [requirement with compliance references]

:
 [requirement with standards/regulations]

:
 [requirement with capacity targets]

:
 [requirement with uptime/availability targets]



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

:
 INT-xxx: [system and integration method]

:
 INT-xxx: [system and integration method]

:
 [Extract any DR-xxx data requirements relevant to integration]

---





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



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

---





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



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

Reference:  for traceability matrix generation and validation

---



[If provided by user - otherwise mark as TBD]

: [budget range]

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

: [duration]

---



Suppliers will be evaluated according to Digital Marketplace guidelines:



 (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

:
  (20%): Quality of proposed solution, alignment with architecture principles
  (10%): Similar projects delivered, relevant domain experience
  (10%): Depth of requirements understanding, risk identification



  (15%): Coverage of essential + desirable skills
  (10%): Relevant project experience, client references, success stories
  (5%): Appropriate roles, seniority levels, availability commitment



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



  (5%): Transparency, justification, flexibility, no hidden costs
  (5%): Approach to project risks, contingency planning, issue management

---





 ✅  document with Mermaid diagrams
 ✅  document
 ✅  and schemas (if applicable)
 ✅  and specifications (if applicable)
 ✅  documentation
 ✅  documentation (for INT-xxx requirements)

Reference: Generate with , 



 ✅  (following architecture principles)
 ✅  and deployment scripts
 ✅  scripts (if applicable)
 ✅  (if applicable)



 ✅  and test cases (linked to requirements)
 ✅  and coverage reports
 ✅  (NFR-P-xxx validation)
 ✅  (NFR-S-xxx validation)
 ✅  (NFR-C-xxx validation)



 ✅  and guides
 ✅ 
 ✅ 
 ✅ 
 ✅  (Requirements → Design → Tests → Code)
 ✅ 



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

---



Vendors must provide:

 
 Proposed solution architecture (aligned with ARC-000-PRIN--REQ-v.md
 : projects/[project]/ARC-.md (if exists)
 : projects/[project]/ARC-.md (if exists)



 : Create vendor evaluation framework and scoring
 : High-Level Design review process for vendor deliverables
 : Detailed Design review process for vendor deliverables
 : Requirements traceability matrix validation

---



:
 ✅ 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

:
 ⚠️ 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

:
 ✅ 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

:
 ✅ 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