arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/azure-research.md

@@ -0,0 +1,157 @@
+# Azure Technology Research Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`/arckit:azure-research` researches Azure services, architecture patterns, and implementation guidance using the Microsoft Learn MCP server for authoritative documentation.
+
+> **Agent Architecture**: This command runs as an autonomous agent via the Task tool. The agent makes 15-30+ MCP calls to gather Azure documentation in its own context window, keeping the main conversation clean. The slash command is a thin wrapper that delegates to the agent.
+
+---
+
+## Prerequisites
+
+### Microsoft Learn MCP Server (REQUIRED)
+
+This command **requires** the Microsoft Learn MCP server to be installed. It will not work without it.
+
+**Installation**:
+
+Add to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "microsoft-docs": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-microsoft-docs"]
+    }
+  }
+}
+```
+
+After installation, restart Claude Code to load the MCP server.
+
+**Slow corporate network?** On TLS-inspecting proxies, VPN tunnels, or congested links, large-scope research prompts can exceed Claude Code's default per-request fetch timeout. Set `MCP_TOOL_TIMEOUT=300000` (5 minutes, in milliseconds) before launching Claude — see [MCP per-request timeout](mcp-servers.md#optional-mcp-per-request-timeout-claude-code-v21142) in the MCP setup guide. Requires Claude Code v2.1.142+.
+
+### Project Prerequisites
+
+- Requirements document (`ARC-*-REQ-*.md`) - **MANDATORY**
+- Data model (`ARC-*-DATA-*.md`) - Recommended for database selection
+- Stakeholders (`ARC-*-STKE-*.md`) - Recommended for priorities
+
+---
+
+## Scenario Matrix
+
+| Scenario | Prompt seed | Focus |
+|---------|-------------|-------|
+| Service selection | "Research Azure services for <capability>" | Maps requirements to Azure services |
+| Architecture pattern | "Research Azure architecture pattern for <pattern>" | Reference architectures from Azure Architecture Center |
+| UK Government | "Research Azure for UK Government <project>" | G-Cloud, data residency, NCSC compliance |
+| AI/ML workloads | "Research Azure AI services for <use case>" | Azure OpenAI, Cognitive Services, ML |
+| Migration | "Research Azure migration options for <workload>" | Azure Migrate, modernization paths |
+| Security assessment | "Research Azure Security Benchmark for <domain>" | Control mapping, Well-Architected security |
+
+Add constraints (budget, classification, region) in the prompt for tailored results.
+
+---
+
+## Command
+
+```bash
+/arckit:azure-research Research Azure services for <project>
+```
+
+Outputs: `projects/<id>/research/ARC-<id>-AZRS-v1.0.md`
+
+> **Auto-versioning**: Re-running this command when a document already exists automatically increments the version (minor for refreshed content, major for changed scope) instead of overwriting.
+
+---
+
+## Long runs: Remote Control + push notifications
+
+`/arckit:azure-research` frequently exceeds 10 minutes as the agent issues dozens of Microsoft Learn MCP calls and fetches full documentation pages for cost and compliance analysis. To avoid babysitting the terminal, pair it with [Claude Code Remote Control](https://code.claude.com/docs/en/remote-control):
+
+```bash
+claude remote-control
+```
+
+Drive the session from claude.ai/code or the mobile app, then enable `/config → Push when Claude decides` so your phone gets a notification on completion or when the agent reaches a decision point (service shortlist confirmation, region selection). ArcKit's minimum Claude Code floor (v2.1.121) already covers the v2.1.110 RC requirement.
+
+Caveats: Pro/Max plans only (no API keys, no Bedrock/Vertex/Foundry), push is a single on/off so chatty agents can over-notify, and the local `claude` process must keep running.
+
+---
+
+## MCP Tools Used
+
+The command uses three Microsoft Learn MCP tools:
+
+| Tool | Purpose |
+|------|---------|
+| `microsoft_docs_search` | Search Azure documentation for services, patterns, best practices |
+| `microsoft_docs_fetch` | Retrieve complete documentation pages for detailed analysis |
+| `microsoft_code_sample_search` | Find Bicep, Terraform, and SDK code samples |
+
+---
+
+## Output Highlights
+
+- **Azure Service Recommendations**: Mapped to specific requirements (FR, NFR, INT, DR)
+- **Architecture Pattern**: Reference architecture from Azure Architecture Center
+- **Well-Architected Assessment**: All 5 pillars evaluated per service
+- **Azure Security Benchmark**: 12 control domains mapped
+- **UK Government Compliance**: G-Cloud, UK regions, NCSC principles
+- **Cost Estimates**: Monthly and 3-year TCO with optimization recommendations
+- **Implementation Guidance**: Bicep/Terraform templates, Azure DevOps pipelines
+
+---
+
+## UK Government Features
+
+When UK Government project detected:
+
+| Area | Coverage |
+|------|----------|
+| **G-Cloud** | Framework reference, service IDs, procurement steps |
+| **Data Residency** | UK South/UK West availability, geo-replication |
+| **Classification** | OFFICIAL, OFFICIAL-SENSITIVE, SECRET suitability |
+| **NCSC** | 14 Cloud Security Principles alignment |
+| **Scottish Government** | AI Strategy, Cyber Resilience Framework |
+
+---
+
+## Follow-on Actions
+
+- Feed Azure findings into `/arckit:diagram` for Azure architecture diagrams
+- Run `/arckit:secure` to validate against UK Secure by Design
+- Run `/arckit:devops` to plan Azure DevOps CI/CD pipelines
+- Run `/arckit:finops` to create Azure FinOps cost management strategy
+- Run `/arckit:adr` to document Azure service selection decisions
+
+---
+
+## Comparison with /arckit:research
+
+| Feature | `/arckit:research` | `/arckit:azure-research` |
+|---------|-------------------|-------------------------|
+| Scope | Multi-cloud, SaaS, open-source | Azure-specific only |
+| Source | Web search, multiple sources | Microsoft Learn MCP (authoritative) |
+| Depth | Build vs buy analysis | Deep Azure service analysis |
+| Compliance | General UK Gov | Azure-specific UK compliance |
+| Code samples | Limited | Bicep, Terraform, SDKs |
+| Cost estimates | High-level | Detailed Azure pricing |
+
+**When to use which**:
+
+- Use `/arckit:research` for cloud-agnostic evaluation or build vs buy
+- Use `/arckit:azure-research` when Azure is the target platform
+
+---
+
+## Resources
+
+- [Microsoft Learn MCP](https://learn.microsoft.com/en-us/training/support/mcp) - MCP server documentation
+- [Azure Architecture Center](https://learn.microsoft.com/azure/architecture/) - Reference architectures
+- [Azure Well-Architected Framework](https://learn.microsoft.com/azure/well-architected/) - Design guidance
+- [Azure Security Benchmark](https://learn.microsoft.com/security/benchmark/azure/) - Security controls
+- [Azure UK Compliance](https://learn.microsoft.com/azure/compliance/offerings/offering-uk-g-cloud) - UK Government compliance

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/backlog.md

@@ -0,0 +1,58 @@
+# Product Backlog Quick Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+Generate a sprint-ready backlog from existing ArcKit artefacts with `/arckit:backlog`. The command converts requirements into groomed stories, groups them into sprints, and exports markdown, CSV, and JSON for tooling.
+
+---
+
+## Input Readiness
+
+| Must Have | Why it matters |
+|-----------|----------------|
+| `ARC-<id>-REQ-v1.0.md` with BR/FR/NFR/INT/DR IDs | Feeds epics, stories, and non-functional tasks |
+| Approved HLD/DLD | Ensures stories reference actual components |
+| Stakeholder analysis | Provides personas for story wording |
+
+*Strongly recommended*: risk register (for priority), business case (for value), traceability matrix (for gaps).
+
+---
+
+## Command Patterns
+
+```bash
+/arckit:backlog                      # default: 8 sprints, 20 pts each
+/arckit:backlog VELOCITY=25 SPRINTS=12 FORMAT=all
+/arckit:backlog PRIORITY=risk        # other options: value, moscow, multi
+```
+
+Outputs land in `projects/<id>/ARC-<id>-BKLG-v1.0.*`.
+
+---
+
+## Backlog Workflow
+
+| Stage | Action |
+|-------|--------|
+| 1. Gather inputs | Confirm artefacts above are up to date |
+| 2. Run command | Choose velocity/sprint count that matches team capacity |
+| 3. Review exports | Check epic grouping, dependencies, and MoSCoW tags |
+| 4. Sprint slicing | Adjust sprint boundaries to respect change freeze / compliance windows |
+| 5. Tool import | Use CSV/JSON for Jira, Azure DevOps, or Trello |
+
+---
+
+## Sprint Planning Checklist
+
+- Stories tie back to requirement IDs in description.
+- Acceptance criteria reflect regulatory constraints (WCAG, GDPR, security).
+- Risks flagged as HIGH appear in Sprint 1–2 for mitigation.
+- Each sprint finishes a vertical slice (discovery, build, test).
+- Service management work (e.g., `/arckit:servicenow`) placed before go-live.
+
+---
+
+## Useful References
+
+- GOV.UK Service Manual on [Agile delivery](https://www.gov.uk/service-manual/agile-delivery) (estimation guidance).
+- `/arckit:traceability` to spot requirements without coverage before backlog generation.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/build.md

@@ -0,0 +1,132 @@
+# Build Harness Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION] | **Claude Code only**
+
+`/arckit:build` orchestrates parallel `/arckit:*` artefact generation against a YAML recipe. It is the only command that doesn't produce a single artefact — it produces *many*, one per recipe target, dispatched as parallel subagents and committed in waves.
+
+---
+
+## Why this exists
+
+Running `/arckit:requirements` then `/arckit:risk` then `/arckit:tcop`… sequentially in main context exhausts the conversation window past about five artefacts. The build harness solves this by spawning one `general-purpose` subagent per artefact per wave, each running its own isolated context. Main session stays small and only orchestrates.
+
+## Quick start
+
+```text
+/arckit:build 001 --plan                 # Dry run — show the wave plan, exit
+/arckit:build 001                        # Build everything in the default uk-saas recipe
+/arckit:build 001 --resume               # Pick up after a halt
+/arckit:build 002 --recipe uk-mod-sovereign
+```
+
+## Arguments
+
+| Arg | Effect |
+|-----|--------|
+| `<project>` | Project ID (e.g. `001`) or full directory name (`001-arckit-saas`) |
+| `--plan` | Dry run; print the wave plan and exit |
+| `--resume` | Read state.json; continue from last incomplete wave |
+| `--target NAME` | Build only `NAME` and its missing dependencies |
+| `--refresh NAME` | Force-rebuild `NAME` and everything downstream |
+| `--no-commit` | Skip the per-wave git commit |
+| `--recipe NAME` | Recipe to use; default `uk-saas` |
+| `--enable ID` | Enable an optional target (e.g. `--enable AIP`) |
+| `--exclude ID` | Exclude a default-on optional target (e.g. `--exclude SVCASS`) |
+
+## Built-in recipes
+
+| Recipe | Targets | Use case |
+|--------|--------:|----------|
+| `uk-saas` | 31 | UK Government managed multi-tenant SaaS — civilian departments, GDS Service Standard, NCSC CAF |
+| `uk-mod-sovereign` | 32 | UK MOD / sovereign / air-gapped — `mod-secure` + `jsp-936`, no SVCASS, sealed-media distribution |
+
+Recipes ship at `${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/{name}.yaml`. Override per project at `.arckit/recipes/{name}.yaml`.
+
+## How it works
+
+1. **Recipe loaded** from `.arckit/recipes/{name}.yaml` if present, else `${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/{name}.yaml`
+2. **Optional-target filter** applied (`--enable` / `--exclude` / recipe defaults)
+3. **Subagent skill smoke-test** — confirms `arckit:*` skills are reachable from `general-purpose` subagents in this session (~5 sec halt-or-go check)
+4. **Topological wave computation** — targets group into waves where every dep is complete; wave 0 is no-deps targets, wave 1 depends only on wave 0, etc.
+5. **Per-wave dispatch** — single assistant message containing N `Agent` tool calls runs in parallel; each subagent invokes its assigned `arckit:*` skill, validates the output, returns a ≤200-word summary
+6. **Per-wave commit** — atomic git commit covering all artefacts in the wave plus the updated `state.json`
+7. **Halt-on-fail** — if any subagent fails or validation fails, write state, do *not* commit, surface a per-target error report. Resume with `--resume`
+8. **Post-build hooks** — `arckit:health` and `arckit:pages` run in parallel after the final target wave
+
+## Path allocation — trust the hook
+
+Workers don't construct filenames or call `generate-document-id.sh` themselves. The plugin's `validate-arc-filename.mjs` PreToolUse hook normalizes paths at write time: allocates the next sequence number for ADR/DIAG, applies `decisions/` and `diagrams/` subfolders, pads project IDs. Workers read the corrected `ACTUAL_PATH` from the Skill tool result and report it back.
+
+## Customizing recipes
+
+To customize the UK-SaaS recipe for your organization:
+
+```bash
+mkdir -p .arckit/recipes
+cp "${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/uk-saas.yaml" .arckit/recipes/uk-saas.yaml
+# Edit .arckit/recipes/uk-saas.yaml — add/remove targets, change ADR topics, change defaults
+/arckit:build 001 --plan                 # Confirm the new wave plan
+```
+
+The same pattern works for `uk-mod-sovereign`. To create a fresh recipe (e.g. `eu-saas`):
+
+```bash
+cp "${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/uk-saas.yaml" .arckit/recipes/eu-saas.yaml
+# Edit — change recipe: name to "eu-saas", swap UK-specific targets for EU equivalents
+/arckit:build 003 --recipe eu-saas --plan
+```
+
+## State and resumability
+
+`projects/{P}-{NAME}/.arckit/state.json` records the build's progress. Schema:
+
+```json
+{
+  "state_format_version": "0.4",
+  "project_id": "001",
+  "project_name": "001-arckit-saas",
+  "recipe": "uk-saas",
+  "recipe_path": "...",
+  "started_at": "2026-05-03T16:00:00Z",
+  "last_wave_completed": 5,
+  "current_wave": 6,
+  "targets": {
+    "PRIN":   {"status": "complete", "path": "...", "wave": 0, "skill": "arckit:principles"},
+    "REQ":    {"status": "complete", "path": "...", "wave": 1, "skill": "arckit:requirements"},
+    "SVCASS": {"status": "pending"}
+  }
+}
+```
+
+The recipe path is recorded so `--resume` works deterministically across recipe edits.
+
+## When NOT to use this
+
+- **Single-artefact tweaks** — just call `/arckit:requirements` etc directly
+- **First-time exploration of ArcKit** — start with `/arckit:start` for guided onboarding
+- **CI / scripted runs** — not yet supported (planned v0.6 with `--validate-only`)
+
+## Build provenance
+
+Every artefact written by the build harness gets a `## Build Provenance` block injected by `provenance-stamp.mjs`, recording the recipe, wave, target ID, requested effort, and effective effort. See [Plugin Hooks → Provenance stamping](../../CLAUDE.md#provenance-stamping-provenance-stampmjs) in CLAUDE.md.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| Smoke-test halts: "subagents do not have access to plugin skills" | Plugin enabled at project-scope only | Enable at user-scope, or run `claude --print '/skill list'` to confirm |
+| Wave halts with "unresolvable cycle" | Bad `deps:` in custom recipe | Run `--plan` and inspect cycle target list |
+| `--resume` re-runs targets that already completed | `state.json` corrupted, deleted, or `recipe_path` mismatch | Delete `state.json` and re-run from scratch with `--target` |
+| ADR-009 written when ADR-008 already exists | Hook auto-allocated next slot | Expected behaviour — multi-instance numbering is monotonic |
+
+## See also
+
+- [`SKILL.md`](../../arckit-claude/skills/arckit-build/SKILL.md) — full orchestration spec
+- [`recipes/uk-saas.yaml`](../../arckit-claude/skills/arckit-build/recipes/uk-saas.yaml) — annotated reference recipe
+- [`recipes/uk-mod-sovereign.yaml`](../../arckit-claude/skills/arckit-build/recipes/uk-mod-sovereign.yaml) — sovereign-deployment variant
+- [Plugin Hooks → Provenance stamping](../../CLAUDE.md#provenance-stamping-provenance-stampmjs) — how build provenance is captured
+
+---
+
+**Generated by**: ArcKit `/arckit:build` documentation
+**ArcKit Version**: [VERSION]

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/business-capability-map.md

@@ -0,0 +1,68 @@
+# Business Capability Map Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:business-capability-map` creates the business architecture baseline for TOGAF ADM Phase A. It maps capability hierarchy, value streams, capability maturity, heatmaps, and requirement or principle traceability.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| ADM preliminary (`ARC-<id>-ADMP-v1.0.md`) | Mandatory scope, vision, drivers, constraints |
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Business and functional requirements to map to capabilities |
+| Stakeholder analysis (`ARC-<id>-STKE-v1.0.md`) | Value expectations, owners, outcomes, pain points |
+| Global principles (`ARC-000-PRIN-v1.0.md`) | Business architecture guardrails |
+| Application inventory (`ARC-<id>-APP-v1.0.md`) | Optional current application support for each capability |
+
+---
+
+## Command
+
+```bash
+/arckit:business-capability-map <project ID or capability scope>
+```
+
+Output: `projects/<id>/ARC-<id>-BPCM-v1.0.md`
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Capability Hierarchy | Level 1 to Level 3 capability model |
+| Value Streams | How capabilities support end-to-end value delivery |
+| Maturity Assessment | Current and target maturity for each capability |
+| Capability Heatmap | Visual prioritisation by maturity, value, or risk |
+| Requirement Traceability | Requirement-to-capability mapping |
+| Principle Alignment | Capability design alignment to architecture principles |
+| Traceability | Source artefacts and downstream handoffs |
+
+---
+
+## Workflow
+
+1. Run `/arckit:adm-preliminary` to define the scope and vision.
+2. Run `/arckit:business-capability-map` to build the business capability baseline.
+3. Use `/arckit:application-inventory` to map applications to capabilities.
+4. Use `/arckit:gap-analysis` to identify weak or missing capability support.
+
+---
+
+## Review Checklist
+
+- Capabilities are named as stable business abilities, not projects or systems.
+- Capability levels are consistent and do not mix process steps with outcomes.
+- Each critical capability has an owner, current maturity, and target maturity.
+- High-value or high-risk capabilities are visible in the heatmap.
+- Requirements and principles are traceable to capability decisions.
+
+---
+
+## Related Commands
+
+- `/arckit:application-inventory` - Attach applications to capabilities.
+- `/arckit:gap-analysis` - Prioritise capability gaps.
+- `/arckit:transition-architecture` - Turn capability gaps into work packages.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/business-case.md

@@ -0,0 +1,68 @@
+# Strategic Outline Business Case (SOBC) Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+Use `/arckit:sobc` to produce HM Treasury Green Book Strategic Outline Business Cases. The command pulls from stakeholders, risks, and principles to assemble the five-case model with traceability back to ArcKit artefacts.
+
+---
+
+## Flow at a Glance
+
+```text
+1. /arckit:principles
+2. /arckit:stakeholders
+3. /arckit:risk
+4. /arckit:sobc   ← generates SOBC (`projects/<id>/ARC-<id>-SOBC-v1.0.md`)
+5. /arckit:requirements (only if SOBC approved)
+```
+
+*Do not skip steps 2–3: stakeholder drivers feed benefits; risks drive optimism bias and management case.*
+
+---
+
+## Five-Case Matrix
+
+| Case | Key Questions | ArcKit Inputs | Output Highlights |
+|------|---------------|---------------|-------------------|
+| Strategic | Why change? Who cares? | Stakeholder map, principles, problem statement | Problem/vision, stakeholder alignment, scope |
+| Economic | Which option wins? | Risk register, research, Wardley map (optional) | Option shortlist, cost/benefit table, NPV & ROI |
+| Commercial | How will we buy? | Procurement strategy, supplier insights | Route to market (G-Cloud/DOS/open tender), contract model |
+| Financial | Can we afford it? | Cost estimates, finance constraints | Funding profile, affordability analysis, sensitivity |
+| Management | Can we deliver it? | Project plan, risk register, governance model | Delivery approach, roles (SRO/SI), change plan, benefits realisation |
+
+---
+
+## Command Usage
+
+```bash
+# minimal
+/arckit:sobc Create SOBC for NHS appointment booking modernisation
+
+# emphasise public sector controls
+/arckit:sobc Create SOBC for HMRC cloud migration referencing TCoP and spend controls
+```
+
+Outputs are markdown-first (`projects/<id>/ARC-<id>-SOBC-v1.0.md`). Use Docs → Export to produce PDF if needed.
+
+---
+
+## Review Checklist
+
+- Executive summary states investment ask, recommendation, and headline benefits.
+- Benefits map back to stakeholder goals (IDs referenced in text).
+- Risk section cites HIGH risks with mitigation owners and review cadence.
+- Procurement route aligns with spend controls (Digital Marketplace, OJEU, etc.).
+- Management case lists governance forums and stage gates.
+- Annex includes dependencies on related programmes (if any).
+
+---
+
+## After the SOBC
+
+| If outcome is… | Next step |
+|----------------|-----------|
+| Approved | Proceed to `/arckit:requirements`, update project plan, and start procurement preparation. |
+| Conditional | Address actions (often risk mitigations or cost refinements) then re-run `/arckit:sobc`. |
+| Rejected | Revisit stakeholder goals, problem statement, or option appraisal; consider discovery reset. |
+
+Store the final SOBC alongside board minutes and upload to approval tooling as evidence.