# atelier-fashion/sdlc-toolkit architecture

> Architecture diagram of the GitHub repository atelier-fashion/sdlc-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atelier-fashion/sdlc-toolkit
- Repository: https://github.com/atelier-fashion/sdlc-toolkit

## Overview

1. **What this repository is**
   - This is not an application runtime repo; it is a **process/tooling repo** for SDLC workflow support in Claude Code.
   - Its main purpose is to provide **reusable agent skills** and **document templates** for spec-driven development.

2. **Top-level architecture**
   - The repo is split into two asset types:
     - `*/SKILL.md` directories: one skill per SDLC action.
     - `templates/*.md`: reusable document templates for specs, tasks, bugs, assumptions, lessons, and reviews.
   - `README.md` is the orchestration layer that explains how the skills, templates, and downstream project artifacts fit together.

3. **Skill subsystem**
   - Each skill directory (`init`, `spec`, `architect`, `validate`, `review`, `reflect`, `wrapup`, `bugfix`, `status`, `analyze`, `optimize`, etc.) contains a `SKILL.md` file.
   - These skills represent **workflow phases**, not application modules. They encode how Claude Code should behave for each step in the SDLC.
   - The skills are intended to be mounted into Claude Code via a symlink at `~/.claude/skills`.

4. **Template subsystem**
   - The `templates/` directory centralizes the canonical artifact shapes used across workflows.
   - Templates cover the main outputs of the process: requirement specs, technical tasks, bug reports, assumptions, lessons learned, and review prompts.
   - This keeps generated artifacts consistent across different projects that consume the toolkit.

5. **Primary data flow**
   - The intended flow is: **feature request → spec → validation → architecture → task breakdown → implementation in target repo → reflection/review → wrap-up**.
   - For defects, the flow is shorter: **bug report → analysis → fix → verification**.
   - The toolkit itself does not store the feature implementation; it guides the generation and review of artifacts in the consuming codebase.

6. **Boundary between toolkit and project repos**
   - This repo holds the **shared process logic**.
   - Each consuming codebase holds its own `.sdlc/` directory, which contains project-specific context, specs, knowledge, and copied templates.
   - That boundary is important: the toolkit is reusable across repos, while the `.sdlc/` folder is the per-project state store.

7. **Initialization and bootstrap path**
   - `/init` is the entry point for a new project.
   - It creates the `.sdlc/` structure in the target repo and copies the shared templates/context needed for project-specific work.
   - This makes downstream repos self-contained for SDLC artifacts while still using the shared toolkit as the source of truth for process.

8. **Validation and quality-control path**
   - `/validate` acts as a gate between phases, ensuring outputs are complete before advancing.
   - `/review` and `/reflect` add post-implementation checks: one external/multi-agent style review, one self-review before formal review.
   - These steps form the repository’s quality boundary, preventing unvetted specs, architectures, or implementations from moving forward.

9. **Operational and maintenance skills**
   - `/status` provides visibility into the current SDLC state across work items.
   - `/analyze` is for codebase health auditing, and `/optimize` is for API cost/performance scanning.
   - `/wrapup` closes the loop by handling completion activities such as commit/merge/deploy updates and artifact cleanup.

10. **Technology and execution environment**
   - The repo is fundamentally **Markdown-based process content** designed for **Claude Code**.
   - Git is used for versioning and distribution; a symlink exposes the repo as a Claude skill library.
   - There is no application server, database, or build pipeline here; the meaningful “runtime” is the LLM-assisted SDLC workflow executed in consuming repositories.

11. **How to diagram it**
   - Model this repo as a **shared process library** feeding multiple project repos.
   - Show three main zones:
     - **Toolkit repo**: skills + templates + README guidance.
     - **Claude Code runtime**: loads skills from the symlinked directory.
     - **Target project repos**: hold `.sdlc/` artifacts and actual product code.
   - The arrows should emphasize artifact generation and review flows, not application data flow.

12. **Key architectural takeaway**
   - The central architectural pattern is **process-as-assets**: the repo packages SDLC behavior into reusable Markdown instructions and templates.
   - Its value lies in standardizing how plans, checks, and wrap-up work are produced across many codebases, while keeping per-project state outside the toolkit itself.

Main entry points: [`README.md`](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/README.md) (README), [`templates`](https://github.com/atelier-fashion/sdlc-toolkit/tree/main/templates) (Templates), [`init/SKILL.md`](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/init/SKILL.md) (Init), [`spec/SKILL.md`](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/spec/SKILL.md) (Spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_toolkit["Toolkit Repo"]
  node_readme["README<br/>orchestration<br/>[README.md]"]
  node_skill_lib["Skills<br/>workflow assets"]
  node_template_lib["Templates<br/>document assets"]
  node_init_skill["Init<br/>bootstrap skill<br/>[SKILL.md]"]
  node_spec_skill["Spec<br/>planning skill<br/>[SKILL.md]"]
  node_architect_skill["Architect<br/>design skill<br/>[SKILL.md]"]
  node_validate_skill["Validate<br/>gate skill<br/>[SKILL.md]"]
  node_review_skill["Review<br/>quality skill<br/>[SKILL.md]"]
  node_reflect_skill["Reflect<br/>self-review skill<br/>[SKILL.md]"]
  node_wrapup_skill["Wrapup<br/>closure skill<br/>[SKILL.md]"]
  node_bugfix_skill["Bugfix<br/>defect skill<br/>[SKILL.md]"]
  node_status_skill["Status<br/>tracking skill<br/>[SKILL.md]"]
  node_analyze_skill["Analyze<br/>audit skill<br/>[SKILL.md]"]
  node_optimize_skill["Optimize<br/>performance skill<br/>[SKILL.md]"]
  node_proceed_skill["Proceed<br/>flow skill<br/>[SKILL.md]"]
  node_sprint_skill["Sprint<br/>coordination skill<br/>[SKILL.md]"]
  node_canary_skill["Canary<br/>check skill<br/>[SKILL.md]"]
end

subgraph group_runtime["Claude Code"]
  node_claude_code(("Claude Code<br/>runtime"))
  node_skills_mount["Skills Mount<br/>symlink"]
end

subgraph group_project["Target Repos"]
  node_sdlc_state[(".sdlc<br/>project state")]
  node_project_code["Project Code<br/>application repo"]
  node_feature_flow["Feature Flow<br/>artifact flow"]
  node_bug_flow["Bug Flow<br/>artifact flow"]
end

node_readme -->|"describes"| node_skill_lib
node_readme -->|"describes"| node_template_lib
node_readme -->|"orients"| node_skills_mount
node_skill_lib -->|"includes"| node_init_skill
node_skill_lib -->|"includes"| node_spec_skill
node_skill_lib -->|"includes"| node_architect_skill
node_skill_lib -->|"includes"| node_validate_skill
node_skill_lib -->|"includes"| node_review_skill
node_skill_lib -->|"includes"| node_reflect_skill
node_skill_lib -->|"includes"| node_wrapup_skill
node_skill_lib -->|"includes"| node_bugfix_skill
node_skill_lib -->|"includes"| node_status_skill
node_skill_lib -->|"includes"| node_analyze_skill
node_skill_lib -->|"includes"| node_optimize_skill
node_skill_lib -->|"includes"| node_proceed_skill
node_skill_lib -->|"includes"| node_sprint_skill
node_skill_lib -->|"includes"| node_canary_skill
node_template_lib -->|"seeds"| node_sdlc_state
node_claude_code -->|"loads"| node_skills_mount
node_skills_mount -->|"points to"| node_skill_lib
node_init_skill -->|"creates"| node_sdlc_state
node_spec_skill -->|"starts"| node_feature_flow
node_validate_skill -->|"gates"| node_feature_flow
node_architect_skill -->|"continues"| node_feature_flow
node_review_skill -->|"checks"| node_feature_flow
node_reflect_skill -->|"prechecks"| node_feature_flow
node_wrapup_skill -->|"closes"| node_feature_flow
node_bugfix_skill -->|"drives"| node_bug_flow
node_status_skill -->|"reads"| node_sdlc_state
node_analyze_skill -->|"audits"| node_project_code
node_optimize_skill -->|"scans"| node_project_code
node_feature_flow -->|"implements in"| node_project_code
node_bug_flow -->|"fixes in"| node_project_code
node_sdlc_state -->|"supports"| node_project_code

click node_readme "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/README.md"
click node_template_lib "https://github.com/atelier-fashion/sdlc-toolkit/tree/main/templates"
click node_init_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/init/SKILL.md"
click node_spec_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/spec/SKILL.md"
click node_architect_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/architect/SKILL.md"
click node_validate_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/validate/SKILL.md"
click node_review_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/review/SKILL.md"
click node_reflect_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/reflect/SKILL.md"
click node_wrapup_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/wrapup/SKILL.md"
click node_bugfix_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/bugfix/SKILL.md"
click node_status_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/status/SKILL.md"
click node_analyze_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/analyze/SKILL.md"
click node_optimize_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/optimize/SKILL.md"
click node_proceed_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/proceed/SKILL.md"
click node_sprint_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/sprint/SKILL.md"
click node_canary_skill "https://github.com/atelier-fashion/sdlc-toolkit/blob/main/canary/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_skill_lib,node_template_lib,node_init_skill,node_spec_skill,node_architect_skill,node_validate_skill,node_review_skill,node_reflect_skill,node_wrapup_skill,node_bugfix_skill,node_status_skill,node_analyze_skill,node_optimize_skill,node_proceed_skill,node_sprint_skill,node_canary_skill toneBlue
class node_claude_code,node_skills_mount toneAmber
class node_sdlc_state,node_project_code,node_feature_flow,node_bug_flow toneMint
```

## Components

### Toolkit Repo

Shared Markdown assets and orchestration for SDLC workflows

- [README](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/README.md): orchestration · Explains how skills, templates, and downstream artifacts fit together · `README.md`
- **Skills**: workflow assets · Reusable SDLC phase instructions packaged as skill directories
- [Templates](https://github.com/atelier-fashion/sdlc-toolkit/tree/main/templates): document assets · Canonical artifact shapes for specs, tasks, bugs, lessons, and reviews · `templates`
- [Init](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/init/SKILL.md): bootstrap skill · Creates per-project SDLC structure and seeds downstream repos · `init/SKILL.md`
- [Spec](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/spec/SKILL.md): planning skill · Turns feature requests into requirement specs · `spec/SKILL.md`
- [Architect](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/architect/SKILL.md): design skill · Shapes technical direction and architecture from validated specs · `architect/SKILL.md`
- [Validate](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/validate/SKILL.md): gate skill · Checks completeness before advancing between SDLC phases · `validate/SKILL.md`
- [Review](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/review/SKILL.md): quality skill · Runs external-style review against work products · `review/SKILL.md`
- [Reflect](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/reflect/SKILL.md): self-review skill · Performs pre-review introspection and learning capture · `reflect/SKILL.md`
- [Wrapup](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/wrapup/SKILL.md): closure skill · Handles completion steps and artifact cleanup · `wrapup/SKILL.md`
- [Bugfix](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/bugfix/SKILL.md): defect skill · Supports bug analysis, repair, and verification workflow · `bugfix/SKILL.md`
- [Status](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/status/SKILL.md): tracking skill · Surfaces current SDLC state across work items · `status/SKILL.md`
- [Analyze](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/analyze/SKILL.md): audit skill · Audits codebase health and structural issues · `analyze/SKILL.md`
- [Optimize](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/optimize/SKILL.md): performance skill · Scans for API cost and performance improvements · `optimize/SKILL.md`
- [Proceed](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/proceed/SKILL.md): flow skill · Advances work through the next SDLC step · `proceed/SKILL.md`
- [Sprint](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/sprint/SKILL.md): coordination skill · Supports sprint-level workflow coordination · `sprint/SKILL.md`
- [Canary](https://github.com/atelier-fashion/sdlc-toolkit/blob/main/canary/SKILL.md): check skill · Provides lightweight preflight or probe behavior · `canary/SKILL.md`

### Claude Code

Execution environment that mounts skills and runs workflows

- **Claude Code**: runtime · Loads mounted skills and executes SDLC guidance
- **Skills Mount**: symlink · Symlinked exposure of the toolkit as a Claude skill library

### Target Repos

Consuming codebases with per-project SDLC state and product code

- **.sdlc**: project state · Per-project store for specs, context, knowledge, and copied templates
- **Project Code**: application repo · Actual product implementation in the consuming repository
- **Feature Flow**: artifact flow · Feature request to spec to validation to architecture to tasks to implementation
- **Bug Flow**: artifact flow · Bug report to analysis to fix to verification

## Connections

- README → Skills: describes · README explains the reusable skill library
- README → Templates: describes · README explains the shared template set
- README → Skills Mount: orients · Connects toolkit assets to Claude Code mounting
- Skills → Init: includes · Skill directories are the primary workflow assets
- Skills → Spec: includes · Skill directories are the primary workflow assets
- Skills → Architect: includes · Skill directories are the primary workflow assets
- Skills → Validate: includes · Skill directories are the primary workflow assets
- Skills → Review: includes · Skill directories are the primary workflow assets
- Skills → Reflect: includes · Skill directories are the primary workflow assets
- Skills → Wrapup: includes · Skill directories are the primary workflow assets
- Skills → Bugfix: includes · Skill directories are the primary workflow assets
- Skills → Status: includes · Skill directories are the primary workflow assets
- Skills → Analyze: includes · Skill directories are the primary workflow assets
- Skills → Optimize: includes · Skill directories are the primary workflow assets
- Skills → Proceed: includes · Skill directories are the primary workflow assets
- Skills → Sprint: includes · Skill directories are the primary workflow assets
- Skills → Canary: includes · Skill directories are the primary workflow assets
- Templates → .sdlc: seeds · Templates are copied into project-local SDLC state
- Claude Code → Skills Mount: loads · Execution environment mounts and reads the skills library
- Skills Mount → Skills: points to · Symlink exposes the toolkit as a skill library
- Init → .sdlc: creates · Bootstraps the project-local SDLC structure
- Spec → Feature Flow: starts · Begins the feature-request-to-spec path
- Validate → Feature Flow: gates · Checks completeness between workflow phases
- Architect → Feature Flow: continues · Moves validated work into technical design
- Review → Feature Flow: checks · Performs external review of work products
- Reflect → Feature Flow: prechecks · Self-review before formal review
- Wrapup → Feature Flow: closes · Finalizes completed work and cleanup
- Bugfix → Bug Flow: drives · Handles the defect-resolution path
- Status → .sdlc: reads · Reports progress from project-local state
- Analyze → Project Code: audits · Inspects the consuming codebase
- Optimize → Project Code: scans · Looks for performance and cost issues in the codebase
- Feature Flow → Project Code: implements in · Artifacts guide implementation in the target repo
- Bug Flow → Project Code: fixes in · Defect flow produces changes in the target repo
- .sdlc → Project Code: supports · Per-project artifacts live alongside the implementation
