Add .claude directory for reference

2026-02-22 13:19:20 +01:00
parent 32d69ea71e
commit 79c8ee790c
23 changed files with 4178 additions and 1 deletions
--- a/.claude/skills/architect/README.md
+++ b/.claude/skills/architect/README.md
@@ -0,0 +1,112 @@
+# Requirements → Architecture Toolkit for Claude Code
+
+Skills and prompts that cover the path from project idea to implementation-ready plan.
+
+---
+
+## The Tools
+
+| Tool                             | Type          | Purpose                                           | Produces                                       |
+|:---------------------------------|:--------------|:--------------------------------------------------|:-----------------------------------------------|
+| `gather-requirements`            | Skill         | Structured requirements interview                 | `REQUIREMENTS.md`                              |
+| `requirements-analyst-prompt.md` | System prompt | Same interview, layered on `/opsx:explore`        | `REQUIREMENTS.md`                              |
+| `architect`                      | Skill         | Collaborative technical design with product owner | `TECHNICAL-SPEC.md` + `IMPLEMENTATION-PLAN.md` |
+
+---
+
+## Workflow
+
+### Without OpenSpec
+
+```
+/gather-requirements  →  REQUIREMENTS.md  →  /architect  →  TECHNICAL-SPEC.md
+                                                           →  IMPLEMENTATION-PLAN.md
+```
+
+### With OpenSpec
+
+```
+claude --append-system-prompt-file requirements-analyst-prompt.md
+  └─► /opsx:explore (structured requirements interview)
+        └─► REQUIREMENTS.md captured
+              └─► /architect (in same or new session)
+                    └─► TECHNICAL-SPEC.md + IMPLEMENTATION-PLAN.md
+                          └─► /opsx:new my-feature
+                                └─► /opsx:ff (informed by all three documents)
+```
+
+---
+
+## Install
+
+### Skills
+
+```bash
+# Project-level
+mkdir -p .claude/skills
+cp -r gather-requirements .claude/skills/
+cp -r architect .claude/skills/
+
+# OR User-level (all projects)
+cp -r gather-requirements ~/.claude/skills/
+cp -r architect ~/.claude/skills/
+```
+
+### System prompt (for OpenSpec workflow)
+
+Keep `requirements-analyst-prompt.md` wherever you like. Reference it at launch:
+
+```bash
+claude --append-system-prompt-file /path/to/requirements-analyst-prompt.md
+```
+
+---
+
+## Usage
+
+### /gather-requirements
+
+```
+$ claude
+> /gather-requirements
+```
+
+Claude interviews you in 6 phases (vision, users, functional, non-functional, constraints, priorities) and writes `REQUIREMENTS.md` with numbered requirement IDs.
+
+### /architect
+
+```
+$ claude
+> /architect
+```
+
+Claude reads `REQUIREMENTS.md` and works through the design collaboratively with you as product owner. You'll discuss and decide together on:
+
+- Architecture approach (monolith, services, serverless, etc.)
+- Technology stack
+- Data architecture
+- API and integration design
+- Testing strategy (your call — Claude presents options)
+- Infrastructure and deployment
+- Security
+- Delivery approach and phasing
+
+After the sessions, Claude writes `TECHNICAL-SPEC.md` and `IMPLEMENTATION-PLAN.md`. All three documents share a common vocabulary of requirement IDs, component names, and task IDs for full traceability.
+
+### OpenSpec prompt
+
+```bash
+claude --append-system-prompt-file requirements-analyst-prompt.md
+> /opsx:explore
+```
+
+Same structured interview, woven into OpenSpec's explore mode. When insights crystallize, Claude offers to capture `REQUIREMENTS.md` before you transition to `/opsx:new`.
+
+---
+
+## Tips
+
+- **Sequence matters.** Requirements first, architecture second. The architect skill expects `REQUIREMENTS.md` to exist.
+- **"I don't know" is fine.** In requirements, unknowns become open questions. In architecture, they become assumptions — clearly marked so the team can revisit.
+- **Iterate.** Both skills update documents in place. Re-run `/architect` after refining requirements.
+- **IDs carry forward.** FR-001 in requirements maps to components in the spec and tasks in the plan. This traceability is the point — it lets the team verify nothing was lost.