Stationery Inventory Management

Tech Stack: TypeScript + Express + React + Vite + Prisma + SQLite + Jest + Playwright

A hands-on Agentic SDLC workshop project for tracking and analyzing stationery inventory usage across 1,500+ microfinance branches.

Quick Start

1. Install Dependencies

# Install backend dependencies
npm install

# Install frontend dependencies
cd src/frontend
npm install
cd ../..

2. Set Up the Database

# Generate Prisma client
npx prisma generate

# Run migrations (after models are added)
npx prisma migrate dev

# Seed the database (after seed data is added)
npm run prisma:seed

3. Run the Application

# Terminal 1: Start backend server
npm run dev:backend

# Terminal 2: Start frontend dev server
npm run dev:frontend

The application will be available at http://localhost:3000

The backend also serves the built frontend (npm run build:frontend) at the same URL, so the app can be demonstrated from the backend alone.

4. Sign In

Authentication goes through the IAM framework integration (POST /api/auth/login) and issues an httpOnly session cookie. The seeded accounts are created only when the environment provides SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD and SEED_USER_EMAIL / SEED_USER_PASSWORD; configure local values before running the seed command.

Role	Capabilities
`ADMIN`	Full access, including admin-only routes such as `/api/users` and the Admin menu section
`USER`	Read access only; admin routes return `403 Access denied` and admin menu items are hidden

Session token signing uses AUTH_JWT_SECRET, and the session lifetime is set by AUTH_SESSION_TTL_SECONDS. AUTH_JWT_SECRET is deliberately not committed: outside production the server generates a random per-process key, and setting it is mandatory when NODE_ENV=production.

5. Run Tests

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

# View E2E test report
npm run test:e2e:report

Agentic SDLC Workshop

A hands-on workshop run with multiple parallel teams of 5 or more — each team made up of a PM, Architect, Database Dev, Backend Dev, UI Dev, and QA Engineer — that uses a sequence of specialised GitHub Copilot agents to take a single business requirement all the way to tested, working code: BRD, design, work items (Epics → Features → Stories → Tasks), scaffold, implementation, and Playwright E2E tests — all generated as local files in the repo. Every team works the same requirement independently, then compares approaches and outcomes at the end.

Start Here — Reading Order

If you are new to this framework, read the documents in this order:

Step	File	What it gives you
1	`README.md` (this file)	Overview, folder structure, setup, and quick-start commands
2	`docs/PRE-SETUP-CHECKLIST.md`	Checklist of everything to prepare before the workshop begins
3	`workshop-stack.md`	Fill this in before Phase 2. Your tech stack config — language, framework, database, frontend, paths. See `docs/STACK-SETUP-GUIDE.md` for step-by-step help and ready-to-copy examples.
4	`docs/GHE-COMPLETE-WORKSHOP-FLOW.md`	Recommended GitHub-native flow using GitHub Issues, Projects, Actions, and Copilot agents without Azure DevOps
5	`docs/COMPLETE-WORKSHOP-FLOW.md`	Full base flow, including optional Azure DevOps sync phases
6	`docs/FACILITATOR-GUIDE.md`	Narration scripts and talking points (facilitator only)

Just running the workshop? Read steps 1 → 2 → 3 → 4.
Facilitating for an audience? Read all six in order.

What This Framework Does

Takes a single business requirement as input and produces:

A complete Business Requirements Document
A technical design document with architecture, data model, API contracts, and component structure
A full Agile work breakdown: Epics → Features → User Stories → Tasks (as local Markdown files)
Effort estimates for every work item with reasoning
A capacity-driven sprint plan
A working application scaffolded and implemented for your chosen tech stack
Playwright end-to-end tests covering the implemented features
GitHub-native work tracking through GitHub Issues, GitHub Projects, pull requests, and GitHub Actions
Optional: the full work-item hierarchy synced to Azure DevOps Boards

Prerequisites

Requirement	Notes
VS Code	Latest
GitHub Copilot extension	Latest (signed in)
Git	Any recent version
GitHub CLI (`gh`)	Required for the GitHub-native workshop flow
GitHub Projects	Recommended for sprint planning and backlog visibility
Azure DevOps account	Optional — only required if using the ADO sync phase
ADO MCP server	Optional — only required if syncing work items to ADO Boards

Folder Structure

.github/
  agents/                         Copilot agent definitions
    brd-agent.agent.md
    design-agent.agent.md
    epic-agent.agent.md
    feature-agent.agent.md
    user-story-agent.agent.md
    task-agent.agent.md
    scaffold-agent.agent.md
    implement-agent.agent.md
    unit-test-agent.agent.md
    estimate-agent.agent.md
    sprint-planning-agent.agent.md
    playwright-agent.agent.md
    ado-sync-agent.agent.md
    review-agent.agent.md         (on-demand — use at any time after implementation)
  skills/                         Detailed skill instructions per agent
    create-brd/SKILL.md
    create-design-doc/SKILL.md
    create-epics/SKILL.md
    create-features/SKILL.md
    create-user-stories/SKILL.md
    create-tasks/SKILL.md
    create-scaffold/SKILL.md
    implement-task/SKILL.md
    create-unit-tests/SKILL.md
    create-estimates/SKILL.md
    create-sprintplan/SKILL.md
    create-playwright-tests/SKILL.md
    create-ado-sync/SKILL.md
    review-task/SKILL.md

docs/
  requirements/
    BRD.md                        Generated by brd-agent
  design/
    design-doc.md                 Generated by design-agent
  work-items/
    epics/                        Generated by epic-agent
    features/                     Generated by feature-agent
    stories/                      Generated by user-story-agent
  reports/
    effort-estimate-report.html   Generated by estimate-agent
    sprint-plan-report.html       Generated by sprint-planning-agent
  test-reports/                   Generated by playwright-agent (HTML)
  ado-sync-config.json            ADO connection settings
  ado-sync-state.json             Created by ado-sync-agent (idempotency)
  playwright-mcp-setup.md         Playwright MCP configuration guide

issues/                           Task files generated by task-agent
src/                              Project scaffold and implementation code
e2e/                              Playwright test files generated by playwright-agent

workshop-stack.md                 Tech stack configuration (fill in before Phase 2)
init-workspace.sh                 Workspace initialisation (Mac/Linux)
init-workspace.ps1                Workspace initialisation (Windows)

Setup

1. Clone and initialise the workspace

git clone {your-repo-url}
cd {your-repo}

# Mac/Linux
bash init-workspace.sh

# Windows
.\init-workspace.ps1

2. Prepare GitHub-native work tracking (recommended — no Azure DevOps required)

Use docs/GHE-COMPLETE-WORKSHOP-FLOW.md when running the workshop fully on GitHub. Before the workshop:

Create a GitHub Project for the repository or organisation.
Add Project fields for Type, Priority, Effort, Sprint, and Task Type.
Create repository labels for epic, feature, user-story, task, database, backend, frontend, unit-test, e2e-test, must-have, should-have, and could-have.
Enable Project workflows to auto-add matching issues and move completed work to Done when linked pull requests are merged.

Use GitHub Issues as the work-item system and GitHub sub-issues for the Epic → Feature → User Story → Task hierarchy. In this mode, skip both ado-sync-agent phases entirely.

3. Configure ADO connection (optional — skip if not using Azure DevOps)

Edit docs/ado-sync-config.json:

{
  "organization": "https://dev.azure.com/{your-org}",
  "project": "{your-project-name}",
  "areaPath": "{your-project-name}\\{optional-area}",
  "iterationRootPath": "{your-project-name}\\Sprint"
}

If you are not using Azure DevOps, skip this step. The framework produces all work item files locally and the optional ADO sync phases (Phase 4 and Phase 7) can be omitted entirely.

4. Verify ADO MCP server (optional — skip if not using Azure DevOps)

Ensure the ADO MCP server is connected in VS Code and can list your ADO projects before running the workshop. Full setup instructions — .vscode/mcp.json, authentication via az login or PAT, and verification — are in docs/ado-mcp-setup.md.

Local-only or non-ADO users: Skip this step. The ADO MCP server is not required for any phase except ado-sync-agent.

Running the Framework

Open VS Code with this repository loaded and open the GitHub Copilot Chat panel. For each phase below: select the named agent from the Agent dropdown in the chat panel, type the prompt shown, and press Enter. Phases must run in order — every agent reads the output of the previous one.

Phase 1 — Requirements

Who: PM Agent: brd-agent Prompt: paste the customer requirement text directly into the chat, or reference a file in the repo, e.g.:

create the BRD from requirement.txt

Output: docs/requirements/BRD.md — a structured Business Requirements Document listing actors, functional requirements (FR-XXX), non-functional requirements, business rules, and out-of-scope items. Review it with the team before Phase 2 — every later artifact traces back to it.

Phase 2 — Design

Who: Architect Prerequisite: workshop-stack.md is filled in (no {placeholder} values left). Agent: design-agent Prompt:

create the design document from the BRD

Output: docs/design/design-doc.md — the technical design: architecture overview, data model, API contracts, component structure, and data-testid values. This is the single source of truth that every work-breakdown and implementation agent reads from.

Phase 3 — Work Breakdown

Who: PM (with input from Architect) Run the four agents below in order. Each one reads the output of the previous.

3a — epic-agent

create epics from the design document

Output: docs/work-items/epics/ — one Markdown file per Epic, each covering a major business capability traced to BRD requirements.

3b — feature-agent

create features for all epics

Output: docs/work-items/features/ — one file per Feature, each an independently demonstrable slice of an Epic.

3c — user-story-agent

create user stories for all features

Output: docs/work-items/stories/ — user stories written from the role's perspective with acceptance criteria.

3d — task-agent

create tasks for all user stories

Output: issues/ — typed implementation tasks (DATABASE, BACKEND, UNIT-TEST, FRONTEND, E2E-TEST) ready for the team to pick up.

Phase 4 — ADO Sync, 1st pass (optional — Azure DevOps only)

Skip this phase if you are not using Azure DevOps. Run it now to push the freshly-created backlog (Epics → Features → Stories → Tasks with parent-child links) to Azure DevOps Boards so PMs and stakeholders can review the hierarchy in ADO before any estimation work begins. No estimates or iteration assignments are pushed yet — those come in the 2nd pass (Phase 7).

Who: PM Prerequisites: ADO MCP server connected; docs/ado-sync-config.json filled in. Agent: ado-sync-agent Prompt:

push the backlog to Azure DevOps

Output:

Full Epic → Feature → Story → Task hierarchy created in ADO Boards with parent-child links
docs/ado-sync-state.json — records each work item ID for the 2nd pass

GitHub-native alternative to Phase 4 (recommended if not using ADO)

Use the issue creation and Project setup steps in docs/GHE-COMPLETE-WORKSHOP-FLOW.md:

Create GitHub Issues from the generated Epic, Feature, User Story, and Task files.
Apply the corresponding labels and Project field values.
Link the hierarchy with GitHub sub-issues: Epic → Feature → User Story → Task.
Add issues to the GitHub Project board for backlog and stakeholder review.

Phase 5 — Estimation

Who: PM or Architect Agent: estimate-agent Prompt:

analyse all work and produce the estimate report

Output:

Effort estimates written into every Task, Story, Feature, and Epic file
docs/reports/effort-estimate-report.html — a self-contained HTML summary you can open in any browser to review totals, breakdowns by task type, and the reasoning behind each estimate.

Phase 6 — Sprint Planning

Who: PM Agent: sprint-planning-agent Prompt:

create the sprint plan

The agent will ask three questions about team capacity (developers per role, sprint length, hours per developer per sprint). Answer them in chat.

Output: docs/reports/sprint-plan-report.html — a capacity-driven sprint plan showing which stories land in which sprint, utilisation per role, dependencies, and sprint goals. Open in a browser to review.

Phase 7 — ADO Sync, 2nd pass (optional — Azure DevOps only; skip if you skipped Phase 4)

Re-run the same agent. It detects the existing docs/ado-sync-state.json and switches to update mode — sets Remaining Work from estimates and Iteration from the sprint plan on already-synced items. Never creates duplicates. Any new work items found locally since the 1st pass are created and linked.

Who: PM Agent: ado-sync-agent Prompt:

update ADO with estimates and sprint assignments

Output:

Remaining Work and Iteration fields populated on existing ADO work items
docs/ado-sync-state.json updated with lastUpdated timestamp

GitHub-native alternative to Phase 7 (recommended if not using ADO)

After estimation and sprint planning:

Update the GitHub Project Effort field from the generated estimates.
Assign each issue to the correct Sprint iteration from the sprint plan.
Use Project views grouped by Sprint, Type, Priority, and Status for review.
Keep implementation traceability by linking pull requests with Closes #<issue-number>.

Phase 8 — Scaffold

Who: Architect or any developer Prerequisite: workshop-stack.md has no unfilled {placeholder} values. Agent: scaffold-agent Prompt:

generate the project scaffold

Output: src/ populated with the folder structure, entry-point stubs, dependency manifest (e.g. package.json / requirements.txt / pom.xml), and playwright.config.ts for the chosen stack. Additive only — no existing files are overwritten.

Phase 9 — Implementation

Who: Database Dev → Backend Dev → UI Dev (in dependency order) Implement each task file in issues/ in this order: DATABASE → BACKEND → UNIT-TEST → FRONTEND → E2E-TEST.

implement-agent handles DATABASE, BACKEND, and FRONTEND tasks
unit-test-agent handles UNIT-TEST tasks (run after each BACKEND task)
playwright-agent handles E2E-TEST tasks (Phase 10, after all FRONTEND tasks)

Agent: implement-agent Prompt (one task at a time):

implement issues/01-DATABASE-{name}.md

Output: production code written to the folders defined in workshop-stack.md (e.g. routes_folder, controllers_folder, components_folder). The agent updates the task file's status to done.

Optional — unit tests after each BACKEND task: Agent: unit-test-agent Prompt:

implement issues/{UNIT-TEST-task-file}.md

Output: unit test files written to unit_tests_folder from workshop-stack.md, with one test case per acceptance criterion.

On-demand review: After implementing any task, invoke review-agent with the task file path. It posts a structured review directly in chat — pass/fail per acceptance criterion plus a recommendation to APPROVE or REQUEST CHANGES. Nothing is written to disk; fix any issues and re-invoke on the same task to re-review.

Phase 10 — E2E Testing (optional — requires app to be running)

Skip this phase if the application has not been implemented yet. playwright-agent generates test files from E2E-TEST task acceptance criteria and the design document, then optionally runs them against the running application using the Playwright MCP server.

Requirements:

Application running locally at the baseURL from playwright.config.ts (if present — created by scaffold-agent); otherwise the fallback URL is dev_server_url from workshop-stack.md

Playwright installed (npm install, pip install pytest-playwright, etc.)

Playwright MCP server configured (see docs/playwright-mcp-setup.md)

Who: QA Engineer Agent: playwright-agent Prompt:

create tests for all E2E-TEST tasks

Output:

e2e/*.spec.ts — one TypeScript spec file per feature area, using only data-testid selectors from the design document
docs/test-reports/ — HTML test report (when tests are executed)

To run the tests and view the report:

npx playwright test
npx playwright show-report docs/test-reports

Agent Reference

Agent	Purpose	Reads	Writes
`brd-agent`	Business Requirements Document	Requirement text	`docs/requirements/BRD.md`
`design-agent`	Technical design	BRD	`docs/design/design-doc.md`
`epic-agent`	Epic work items	Design doc, BRD	`docs/work-items/epics/`
`feature-agent`	Feature work items	Epics, design doc	`docs/work-items/features/`
`user-story-agent`	User story work items	Features, BRD, design doc	`docs/work-items/stories/`
`task-agent`	Implementation tasks	Stories, design doc	`issues/`
`scaffold-agent`	Project scaffold	`workshop-stack.md`	`src/` folder structure + entry points
`implement-agent`	Feature implementation	Task files, design doc, `workshop-stack.md`	`src/`
`unit-test-agent` (on-demand)	Unit tests for BACKEND tasks	BACKEND task files, `workshop-stack.md`	Unit test files in `unit_tests_folder`
`estimate-agent`	Effort estimates + report	All work items	Work item files + HTML report
`sprint-planning-agent`	Sprint plan + report	Estimates, stories	HTML report
`playwright-agent`	E2E tests + test report	E2E-TEST tasks, design doc	`e2e/*.spec.ts` + HTML report
`ado-sync-agent` (optional, two-pass)	ADO Boards sync — 1st pass after task breakdown creates the hierarchy; 2nd pass after sprint planning updates Remaining Work and Iteration	All work items, estimates, sprint plan	ADO work items + `docs/ado-sync-state.json`
`review-agent` (on-demand)	Code review vs acceptance criteria	Task file, implemented code, design doc	Structured review reply in chat (no files written)

Key Design Principles

Domain fidelity Every agent preserves the exact entity names, role names, and lifecycle states from the original requirement. Nothing is renamed or generalised without explicit instruction.

Traceability Every work item traces back to a BRD functional requirement (FR-XXX). Every design decision traces to a requirement. Every task traces to a user story. The chain is never broken.

No estimates during work breakdown Estimation is a separate phase. Work breakdown agents never assign effort. This prevents scope being constrained by premature estimates.

Dependency ordering Tasks are always ordered DATABASE → BACKEND → UNIT-TEST → FRONTEND → E2E-TEST. Sprint planning always respects this dependency chain.

Idempotency Every agent handles re-runs gracefully. Files are overwritten, not duplicated. For GitHub-native workshops, use labels, sub-issues, and Project fields to keep the hierarchy visible in GitHub. If using ADO, the ADO sync state file prevents duplicate work items.

Tech-stack agnostic The framework describes patterns and contracts, not specific frameworks, ORMs, or libraries. It works for any technology stack.

Extending the Framework

To add a new agent:

Create .github/agents/{name}.agent.md
Create .github/skills/{skill-name}/SKILL.md
Add the agent to the workshop flow at the appropriate phase
Update the handoff message of the preceding agent

To customise estimation heuristics: Edit .github/skills/create-estimates/SKILL.md Adjust the t-shirt size to hours table and complexity signals.

To customise sprint planning capacity: Fill in team size and sprint length in workshop-stack.md (Universal Optional Fields section). The sprint-planning-agent reads capacity inputs interactively.

To add a new task type: Edit .github/skills/create-tasks/SKILL.md Add the new type to the type table and define its scope rules.

Troubleshooting

Issue	Resolution
Agent renames domain entities	Re-invoke with explicit entity names listed
Mermaid diagrams not rendering	Open file in VS Code Markdown Preview
HTML reports not opening	Open directly in a browser — no server needed
GitHub Issues not visible on Project board	Check Project auto-add workflows and labels
GitHub Project `Effort` or `Sprint` fields not populated	Update the fields from the estimate and sprint reports
ADO sync fails with 401	Refresh your PAT token
ADO sync fails with 404	Check organisation and project name in config
Duplicate work items in ADO	Check `docs/ado-sync-state.json` — re-runs are idempotent (the 2nd pass updates rather than re-creates); only delete stale entries if the ADO item itself was deleted
Sprint plan overcommits capacity	Re-invoke sprint-planning-agent with lower hours per developer

Facilitator Resources

PRE-SETUP-CHECKLIST.md — complete before every workshop
FACILITATOR-GUIDE.md — talking points, timing, and recovery steps
init-workspace.sh / init-workspace.ps1 — workspace initialisation

Built for the Agentic SDLC Workshop. Extend it, adapt it, make it yours.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
docs		docs
e2e		e2e
issues		issues
prisma		prisma
scripts		scripts
src		src
.env		.env
.gitignore		.gitignore
BUSINESS-REQUIREMENTS.txt		BUSINESS-REQUIREMENTS.txt
README.md		README.md
init-workspace.ps1		init-workspace.ps1
init-workspace.sh		init-workspace.sh
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json
workshop-stack.md		workshop-stack.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Stationery Inventory Management

Quick Start

1. Install Dependencies

2. Set Up the Database

3. Run the Application

4. Sign In

5. Run Tests

Agentic SDLC Workshop

Start Here — Reading Order

What This Framework Does

Prerequisites

Folder Structure

Setup

1. Clone and initialise the workspace

2. Prepare GitHub-native work tracking (recommended — no Azure DevOps required)

3. Configure ADO connection (optional — skip if not using Azure DevOps)

4. Verify ADO MCP server (optional — skip if not using Azure DevOps)

Running the Framework

Phase 1 — Requirements

Phase 2 — Design

Phase 3 — Work Breakdown

Phase 4 — ADO Sync, 1st pass (optional — Azure DevOps only)

GitHub-native alternative to Phase 4 (recommended if not using ADO)

Phase 5 — Estimation

Phase 6 — Sprint Planning

Phase 7 — ADO Sync, 2nd pass (optional — Azure DevOps only; skip if you skipped Phase 4)

GitHub-native alternative to Phase 7 (recommended if not using ADO)

Phase 8 — Scaffold

Phase 9 — Implementation

Phase 10 — E2E Testing (optional — requires app to be running)

Agent Reference

Key Design Principles

Extending the Framework

Troubleshooting

Facilitator Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages