# 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.