Requirements & Architecture Framework

A Git-powered framework for defining requirements and architecture, designed for AI-assisted authoring.

Overview

This repository is the single source of truth for:

• Requirements: Epics, Features, Stories
• Architecture: C4 diagrams, ADRs, standards, system ownership

Requirements sync to Jira on merge. Developers check this repo for implementation detail.

Quick Start for Product Owners

1. Start working in a new branch

./spec start

This creates a working branch. You'll be prompted to describe what you're working on.

2. Create Specs with AI

Open Cursor, Copilot, or your AI assistant and use prompts like:

Create a feature:

"Create a feature for mobile document upload in the [squad-name] squad. It should allow customers to photograph and upload documents during onboarding. See the [epic-name] epic for context."

Break it into stories:

"Create stories for the mobile-document-upload feature."

Review and improve:

"Critically review the stories for the mobile-document-upload feature and suggest improvements."

3. Submit for Review

./spec submit

This commits your changes, pushes the branch, and helps you create a PR. Once merged to the main branch, new tasks will be imported to Jira.

---

Example Workflow

Here's a complete example of creating a feature. The workflow alternates between Terminal (CLI commands) and AI Chat (Cursor/Copilot conversation):

---

Terminal: Start a branch

./spec start
# CLI prompts: What are you working on?
# You type: mobile document upload
# CLI creates branch: spec/mobile-document-upload

---

AI Chat: Create the feature

You: Create a feature for mobile document upload in [squad-name] squad. Users should be able to photograph their documents and upload them. Part of the [epic-name] epic.

AI creates domains/[domain]/[squad]/features/mobile-document-upload/spec.md

---

AI Chat: Break into stories

You: Create 3-4 stories for this feature with clear acceptance criteria

AI creates stories in the stories/ folder

---

AI Chat: Review and refine

You: Review these critically - are the ACs testable? Missing edge cases?

AI suggests improvements, you approve changes

---

Terminal: Submit for review

./spec submit
# CLI commits, pushes, and opens a PR

---

For Tech Leads

Tech leads review requirements and add architecture documentation on the same branch.

1. Pick Up the Branch

git fetch origin
git checkout spec/mobile-document-upload

2. Review Requirements

"Review the mobile-document-upload feature and stories. Are the requirements clear enough for implementation? What questions would developers have?"

3. Add Architecture

"Add an architecture.md for this feature. Include sequence diagrams for the key flows, API contracts, and data model changes."

"What systems does this feature need to integrate with? Check system-ownership.md for owners."

"Create an ADR for the document storage approach - should we use S3 or the existing document service?"

4. Push Updates

git add -A
git commit -m "Add architecture for mobile document upload"
git push

The PR now has both requirements (from PO) and architecture (from Tech Lead) for review.

---

Repository Structure

spec/
├── epics/                    # Cross-squad initiatives
├── blueprints/               # Service blueprints (design artifacts)
├── architecture/             # Organization-wide architecture
│   ├── c4/                   # System diagrams
│   ├── adrs/                 # Decision records
│   └── standards/            # Guidelines
├── domains/                  # Organised by domain → squad
│   ├── [domain-1]/
│   │   ├── [squad-a]/
│   │   └── [squad-b]/
│   └── [domain-2]/
│       └── [squad-c]/
├── templates/
└── knowledge/                # Personas and domain knowledge

Squad Folder Structure

Each squad folder contains:

{squad}/
├── README.md                 # Squad overview
├── architecture/
│   └── README.md             # Squad architecture & tech stack
└── features/
    └── {feature-slug}/
        ├── spec.md           # Feature specification
        ├── architecture.md   # Feature architecture (optional)
        └── stories/
            └── {story}.md    # Individual stories

Hierarchy

Epic (cross-squad initiative)
└── Feature (squad deliverable)
    └── Story (implementable unit)

Ownership Model

Aspect	Git Owns	Jira Owns
Requirements	Title, owner, AC, scope, dependencies	-
Planning	-	Priority, PI, iteration, sprint
Workflow	-	Status, assignee, points
Identity	Slug (folder/file name)	Key (PROJ-123)

Jira Sync

• On merge to main, items sync to Jira automatically
• Jira assigns keys (PROJ-123) written back to frontmatter
• Features link to parent epics; stories become sub-tasks

Getting Started

See SETUP.md for configuration instructions:

• Configuring your domains and squads
• Setting up Jira integration
• Customizing templates

Links

• Setup Guide - Configure for your organization
• Contributing Guide - Detailed workflow and prompts
• Glossary
• C4 Context Diagram
• System Ownership