How atelier-fashion/sdlc-toolkit works
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 README · templates Templates · init/SKILL.md Init · spec/SKILL.md Spec
Components 23
Toolkit Repo
Shared Markdown assets and orchestration for SDLC workflows
- README · Explains how skills, templates, and downstream artifacts fit together
README.md - Skills · Reusable SDLC phase instructions packaged as skill directories
- Templates · Canonical artifact shapes for specs, tasks, bugs, lessons, and reviews
templates - Init · Creates per-project SDLC structure and seeds downstream repos
init/SKILL.md - Spec · Turns feature requests into requirement specs
spec/SKILL.md - Architect · Shapes technical direction and architecture from validated specs
architect/SKILL.md - Validate · Checks completeness before advancing between SDLC phases
validate/SKILL.md - Review · Runs external-style review against work products
review/SKILL.md - Reflect · Performs pre-review introspection and learning capture
reflect/SKILL.md - Wrapup · Handles completion steps and artifact cleanup
wrapup/SKILL.md - Bugfix · Supports bug analysis, repair, and verification workflow
bugfix/SKILL.md - Status · Surfaces current SDLC state across work items
status/SKILL.md - Analyze · Audits codebase health and structural issues
analyze/SKILL.md - Optimize · Scans for API cost and performance improvements
optimize/SKILL.md - Proceed · Advances work through the next SDLC step
proceed/SKILL.md - Sprint · Supports sprint-level workflow coordination
sprint/SKILL.md - Canary · Provides lightweight preflight or probe behavior
canary/SKILL.md
Claude Code
Execution environment that mounts skills and runs workflows
- Claude Code · Loads mounted skills and executes SDLC guidance
- Skills Mount · Symlinked exposure of the toolkit as a Claude skill library
Target Repos
Consuming codebases with per-project SDLC state and product code
- .sdlc · Per-project store for specs, context, knowledge, and copied templates
- Project Code · Actual product implementation in the consuming repository
- Feature Flow · Feature request to spec to validation to architecture to tasks to implementation
- Bug Flow · Bug report to analysis to fix to verification
Connections 34
- 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