AI coding agents that act like senior engineers — personas, skills, and slash commands for spec-driven development at scale.
An opinionated scaffolding for working with AI coding agents (Claude Code, Cursor, codename it what you want) that treats every session as a recurring contractor on a maturing codebase, not a one-shot magic box.
Drawn from shipping real production systems. Bring your own scar tissue.
agentic-workflow/
├── personas/ ← who the AI is (role + invariants + skills to load)
├── skills/ ← how to do specific work (deep playbooks)
├── commands/ ← slash commands (design system designer + shipper)
├── examples/ ← sanitized example specs, handoffs, rules-lessons
├── docs/ ← how to use this repo
├── install/ ← optional symlink installer
└── design-system/ ← the Studio playground (read this if shipping a DS)
PERSONA → "you are the senior backend engineer; you load these skills"
↓
SKILL → "here is HOW to write a service / test an API / drive a browser"
↓
CODEBASE → your repo, with project-specific docs the personas read
A persona is who the AI is. A skill is how the AI does specific work. The codebase is what the AI is working on. The personas reference skills by relative path; the skills reference your project's docs by convention.
| Folder | What's in it | Read first |
|---|---|---|
personas/ |
9 personas: backend, frontend, fullstack, mobile, demo-director, qa-backend, qa-frontend, qa-fullstack, security | backend.md |
skills/ |
12 skills: hard-lessons, quality-standards, rules, api-design, backend-service-patterns, database-patterns, frontend-fsd, testing-strategy, agent-browser, agent-browser-qa-guide, backend-qa-agent, security-review | hard-lessons.md |
commands/ |
2 slash commands: /design-system-agent, /ship-design-system |
design-system-agent.md |
examples/ |
5 example artifacts: MVP spec, phase spec, rules-lessons, backend QA handoff, frontend QA handoff | README.md |
docs/ |
3 how-to guides: how personas work, how to use the QA agents, how to use the design system commands | how-personas-work.md |
Clone it. Read personas/backend.md, skills/hard-lessons.md, and examples/rules-lessons.md. Steal what fits. This is the lowest-commitment path and probably what most people will do.
Pick the personas and skills that fit your stack. Copy them into your project's docs/ folder (or ~/.claude/skills/ if you're using Claude Code). Edit them to match your domain. The cross-references inside the files use relative paths — skills/hard-lessons.md, not absolute paths — so they'll work wherever you put them, as long as the folder structure is preserved.
Clone this repo, then symlink the skills/ and personas/ into your Claude Code config (or equivalent). See INSTALL.md for details.
git clone https://github.com/spiderocious/agentic-workflow.git
cd agentic-workflow
./install/symlink.shYou're starting a new backend feature. Open Claude Code (or your tool of choice) in your target project. Tell the agent:
Load
~/agentic-workflow/personas/backend.mdand follow it. Read the skills it lists. Then build feature X per the spec indocs/specs/feature-x.md.
The agent reads the persona, which tells it to load 6 skills. Those skills include hard-lessons.md — every bug that's already happened, encoded as a rule. By the time the agent writes code, it's seen the pattern that bit you last quarter and won't repeat it.
When the agent finishes, you ask for a QA handoff. The backend persona has a template for that. The QA handoff format matches what the qa-backend.md persona expects to read. Hand the handoff to a QA agent (or yourself) and the loop closes.
The default failure mode of AI-assisted coding is the vacuum problem: the agent doesn't know what your team has already learned the hard way. Every session starts cold. Every mistake gets re-made.
This repo is an attempt to fix that by encoding the lessons in files the agent reads on every session. The agent isn't smarter — it just has access to your scar tissue.
The system reflects an explicit doctrine:
- Strict TypeScript, ban
any, zero-dep where possible. - Layered architecture with hard boundaries — services return
ServiceResult<T>, never throw; money is integer kobo/cents, never float. - High QA bar, no DB mocks — integration tests use real Postgres via Testcontainers.
- Codify weaknesses into agent specs — the longest persona in the repo (
demo-director.md, 27KB) is the one for the work I'm worst at.
If those don't match your doctrine, fork the repo and edit. The files are deliberately small and modular for exactly that reason.
The full philosophy is written up in two blog posts:
- How I Use AI to Code Effectively, Part 1: Spec-Driven Development & Review at Scale — coming soon
- How I Use AI to Code Effectively, Part 2: Agents, Testing & Automation — coming soon
- Not a framework. No code to install, no CLI to run (except an optional symlink installer). These are just markdown files.
- Not an "agent platform." This is a collection of prompts and conventions, not a runtime.
- Not opinionated about which AI you use. The personas don't name a specific model. They work with anything that reads markdown.
MIT. See LICENSE.
Built and maintained by @spiderocious. Drawn from production systems, internal playbooks, and the bugs that taught me to write them.
If you find this useful or extend it, let me know — I'm always interested in how other people are scaffolding their AI workflow.