Two production-grade Claude Code skills / plugins that turn Claude into a disciplined senior developer or senior software architect — one for working safely on existing/legacy codebases, and one for architecting new projects from scratch with proper documentation, business logic tracking, and testing discipline.
Built for developers, teams, and freelancers who want consistent, predictable, well-documented AI-assisted development instead of ad-hoc, undocumented changes that break production or leave no trail for the next engineer.
🔍 Keywords: Claude Code skills, Claude Code plugins, Claude Code marketplace, AI coding agent workflow, senior developer AI prompt, software architecture skill, AI pair programmer, safe refactoring AI, business logic documentation, API documentation generator, Claude Code SKILL.md examples, agentic coding best practices.
- ❓ Why this exists
- 📦 What's included
- ⚙️ How it works
- 🚀 Installation
- 💬 Usage examples
- 📁 Documentation structure these skills produce
- ❔ FAQ
- 🔒 Security & trust
- 🤝 Contributing
- 📜 License
AI coding agents are powerful, but left unguided they tend to:
- 🔁 Rewrite working code because they "prefer" a different pattern
- 🎲 Silently invent business rules when requirements are ambiguous
- 🧨 Make sweeping, unrelated refactors alongside a small fix
- 📭 Ship code with no documentation trail, so the next developer (human or AI) has to reverse-engineer intent
- 🏗️ Skip proper architecture and testing planning on greenfield projects
Dev Workflows solves this by giving Claude a strict, senior-engineer operating procedure — depending on whether you're working on an existing codebase or starting a new project — including a standard docs/ structure (architecture, business logic, API, database, integrations, security, known issues, ADRs) that stays synchronized with every change.
This repository is a Claude Code plugin marketplace containing two independent, installable skills.
For working on an existing production or actively developed codebase.
- 🔎 Explores the codebase before making changes (entry points, routes, services, DB, jobs, integrations, tests)
- 🧐 Treats existing code as not automatically correct — confirms business rules instead of assuming them
- ✂️ Makes the smallest safe change that solves the task — no unrelated refactors
- 🔗 Traces full request/data flow before touching critical logic
- 🛡️ Protects production data — never runs destructive DB operations without explicit confirmation
⚠️ Flags breaking API changes clearly- 🔄 Keeps
docs/in sync after every change (only updates what's relevant) - 📋 Produces a structured end-of-task report: what changed, files touched, tests run, docs updated, and any breaking changes or manual verification needed
Best for: bug fixes, feature additions, refactors, API changes, and maintenance work on any live codebase.
For starting a brand-new software project from scratch.
- 📝 Runs structured requirement discovery before writing any code (users, workflows, roles, data, APIs, integrations, scale, edge cases)
- 📚 Sets up a documentation foundation before implementation (
ARCHITECTURE.md,BUSINESS_LOGIC.md,API.md,DATABASE.md,.env.example, etc.) - 🧱 Follows a strict build order: Requirement → Business Rule → Domain Model → Data Model → API Design → Implementation → Tests → Documentation
- 📖 Documents every major workflow's triggers, rules, calculations, exceptions, and side effects
- 🗄️ Designs database schema, indexes, and API contracts deliberately — not by accident
- 🔐 Enforces backend-side authorization (never relies on frontend-only checks)
- 🧾 Creates Architectural Decision Records (ADRs) for consequential technical choices
- 🎯 Avoids over-engineering, premature optimization, and unnecessary dependencies
Best for: greenfield apps, MVPs, new services, and any project where you want architecture and documentation done right from day one.
Both skills are plain Markdown files with YAML frontmatter — no scripts, no hooks, no external code execution. Claude Code reads the description field in the frontmatter and automatically activates the matching skill based on your conversation context (e.g. "fix this bug in our existing repo" triggers existing-project-dev, while "let's start a new SaaS project" triggers new-project-architect).
You can also invoke a skill's mindset explicitly at any time by referencing it in your prompt.
If you use the Claude Code CLI (terminal-based, installed via npm install -g @anthropic-ai/claude-code):
/plugin marketplace add mba8487143/dev-workflows
/plugin install existing-project-dev
/plugin install new-project-architectUpdate anytime with:
/plugin marketplace update
⚠️ Note:/plugincommands work in the Claude Code CLI only. They are not available inside the Claude Desktop app's "Code" tab, which runs a separate system with its own slash commands.
If you're using Claude Desktop, Cowork, or any environment where /plugin isn't available, clone the repo and copy the skill folders directly into your local skills directory:
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/mba8487143/dev-workflows.git temp
cp -r temp/plugins/existing-project-dev/skills/existing-project-dev ./
cp -r temp/plugins/new-project-architect/skills/new-project-architect ./
rm -rf tempThis places both skills in ~/.claude/skills/, where compatible Claude environments pick them up automatically.
Once installed, just talk to Claude naturally — no special syntax needed:
| 💬 You say | 🎯 Skill triggered |
|---|---|
| "Fix the timezone bug in our payments service" | existing-project-dev |
| "Add a new endpoint to this existing Laravel API" | existing-project-dev |
| "I want to start a new project — a subscription-based fitness app" | new-project-architect |
| "Design the database and API for a brand-new booking system" | new-project-architect |
Both skills work toward (or maintain) the same standard docs/ layout, so any project using them stays consistently documented:
docs/
├── ARCHITECTURE.md 🏛️ layers, modules, data flow, infra
├── BUSINESS_LOGIC.md 📖 workflow rules, triggers, edge cases
├── API.md 🔌 endpoint-by-endpoint reference
├── DATABASE.md 🗄️ schema, relationships, indexes
├── INTEGRATIONS.md 🔗 external services, retries, fallback
├── QUEUES_AND_CRONS.md ⏱️ jobs, workers, schedules
├── DEPLOYMENT.md 🚢 infra/deploy requirements
├── SECURITY.md 🔐 auth, authz, sensitive operations
├── KNOWN_ISSUES.md 🐛 confirmed limitations
├── CHANGELOG.md 📝 meaningful change history
└── decisions/ 🧾 Architectural Decision Records (ADRs)
Does this run any code, scripts, or hooks on my machine? 🚫 No. Both skills are instruction-only Markdown files. They contain no scripts, hooks, MCP servers, or network calls.
Will this slow Claude down or use extra tokens unnecessarily? ⚡ No. Skills are only loaded into context when relevant to your request (Claude Code uses progressive disclosure), so there's no meaningful overhead when you're not using them.
Can I use just one of the two skills?
✅ Yes — install only the one you need (existing-project-dev or new-project-architect).
Can I customize the instructions?
✏️ Yes. After installing manually (Option 2), edit the SKILL.md files directly in ~/.claude/skills/ to match your team's conventions.
Does this work with any programming language or framework? 🌐 Yes — the workflow is language/framework-agnostic. It focuses on process (exploration, planning, documentation, safety) rather than specific syntax.
- 🚫 No scripts, hooks, MCP servers, or external network calls — plain Markdown instructions only
- 👀 Fully open source and readable — review the
SKILL.mdfiles yourself before installing - 🔐 Public repository with restricted write access — only the maintainer can push changes to
main
Issues and suggestions are welcome. If you'd like to propose a change, open an issue describing the improvement before submitting a pull request.
MIT — free to use, modify, and redistribute.
⭐ Maintained by @mba8487143. If this helped your workflow, consider starring the repo so other developers can find it.