Multi-LLM Context Driven Development
English | Português (Brasil) | Español
A structured pipeline — master docs, GitHub Issues, and 8 focused agents — that takes a project from a raw idea to a merged PR.
Core advantages: Master Docs as Source of Truth • GitHub-Native • Zero Lock-in Beyond gh
CoDriDe is a Context Driven Development (CDD) framework: a set of commands and agents that structure how a project goes from a raw idea to a merged PR — with a persistent, versioned source of truth (master docs) that every feature is checked against, and GitHub Issues as the system of record for project management. It runs natively on four AI coding CLIs — Claude Code, Gemini CLI, Codex CLI, and GitHub Copilot CLI — from a single canonical source (see Multi-LLM Support).
This repo is the framework: there's no application code here. You copy your tool's generated folder (.claude/ + CLAUDE.md for Claude Code, or another CLI's own native equivalent) into the project you actually want to build, and CoDriDe's commands become available there.
- Context that evaporates between sessions: every feature re-derives "how do we build things here" from scratch, and there's nothing to check a change against except a reviewer's memory.
- No source of truth to check a change against: without master docs, "does this match our architecture" is a guess, not a check.
- AI-generated code that drifts from real conventions: implementation happens without ever reading the ADRs or patterns that already decided how this should be built.
- 🚀 Structuring a brand-new project from day one, with living master docs from the start
- 🔧 Bringing a disciplined product → engineering pipeline to an existing codebase
- 🧪 BDD/TDD-driven feature work, where acceptance criteria survive from spec to test
- 📐 DDD-aware architecture design for the features whose domain is complex enough to warrant it
- 🗂️ Keeping GitHub Issues honest — synced from the same feature docs that specced the work
- One of the four supported CLIs: Claude Code, Gemini CLI, Codex CLI, or GitHub Copilot CLI
ghCLI, installed and authenticated (gh auth status)- Git
The steps and examples below use Claude Code's syntax — CoDriDe's native, canonical implementation. Using another tool? The same 6 steps apply; see your CLI's exact invocation syntax in its own guide — Gemini CLI, Codex CLI, GitHub Copilot CLI — or in Multi-LLM Support further down.
Step 1: Get the framework
git clone https://github.com/edilson-silva/codride.gitStep 2: Copy it into your project
cp -r codride/.claude codride/CLAUDE.md /path/to/your-project/
cd /path/to/your-projectStep 3: Run the health check
claude "/engineer:doctor"Step 4: Configure project preferences (docs language, Artifacts, more later)
claude "/meta:preferences"Step 5: Scan the codebase (optional, but sharpens everything else)
claude "/engineer:discover"Step 6: Warm up and start
claude "/warm-up"This is the fast path: it goes straight from /product:collect to /product:spec, relying on the checks spec already does internally (equivalent to refine and validate — see the note in the Command Reference). To see the full staged flow, with refine and validate as separate steps, see "Example 1" further down.
claude "/product:collect Users can't reset their password if their email has a plus-alias"
# → creates a GitHub issue
claude "/product:spec #42"
# → expands it into a full PRD with BDD acceptance criteria
claude "/engineer:context fix/password-reset-plus-alias"
# → interview → .claude/work/fix/password-reset-plus-alias/context.md
claude "/engineer:architecture fix/password-reset-plus-alias"
# → design → .claude/work/fix/password-reset-plus-alias/architecture.md, cross-checked against context.md
claude "/engineer:plan fix/password-reset-plus-alias"
# → .claude/work/fix/password-reset-plus-alias/plan.md, phased into ~2h-sized chunks
claude "/engineer:work .claude/work/fix/password-reset-plus-alias"
# → implements phase by phase, test-first; syncs the GitHub issue as it goes
claude "/engineer:pre-pr"
# → validate + review run in parallel, then sync-docs + coverage
claude "/engineer:pr"
# → commits, opens the PR, moves the issue to reviewYou don't need every piece on day one — /engineer:context and /engineer:architecture work fine without master docs or a discovery briefing; they just have less context to draw on.
The 6-step setup above works for any project, but an existing codebase already has signal worth mining — code, README, issues, ADRs — so the bootstrap commands default to analyzing that material first and only interview you to fill the gaps. This is Analysis mode; a brand-new/empty project instead runs Collection mode, a from-scratch interview (see the FAQ).
Steps 1-4: same as the 6-step setup — copy .claude/ in, run /engineer:doctor, run /meta:preferences, run /engineer:discover.
/engineer:discover is the fast, automatic pass over the codebase: no interview, safe to re-run incrementally as the code evolves. It writes:
docs/technical-context/project-briefing.md— master index + summarydocs/technical-context/briefing/critical-rules.md— the 3-5 most critical rules, copied in full into every futurecontext.mddocs/technical-context/briefing/adrs-summary.md— indexed ADR summaries (created with a "none yet" note if the project has no ADRs)docs/technical-context/briefing/backend-conventions.md,frontend-conventions.md,mobile-conventions.md— folder structure, naming, code patterns, one file per domain actually detected (not mutually exclusive)docs/technical-context/briefing/tech-stack.md— runtime, framework, database/ORM, key libraries
It also runs adr-compliance-checker against the existing code once the ADRs above are cataloged — that's reported directly in the command's output, not written to a file.
Step 5 (optional, deeper): the full technical master doc
claude "/bootstrap:tech-docs [links to repo/docs, if any]"Heavier than /engineer:discover — it interviews you (~10 questions) about architecture decisions, workflows, and known challenges, then writes the complete technical-context architecture:
docs/technical-context/index.md— master indexdocs/technical-context/project_charter.md— vision, success criteria, scope, stakeholdersdocs/technical-context/adr/— draft ADRs for decisions it found in the code but that were never written downdocs/technical-context/CLAUDE.meta.md— AI development guide (code style, gotchas, patterns)docs/technical-context/CODEBASE_GUIDE.md— annotated directory structure, data flow, integrationsdocs/technical-context/BUSINESS_LOGIC.md— domain rules and workflows (if complex domain logic exists)docs/technical-context/API_SPECIFICATION.md— endpoints, auth, data models (if APIs exist)docs/technical-context/CONTRIBUTING.md— branch strategy, review process, testing requirementsdocs/technical-context/TROUBLESHOOTING.md— common issues and debugging approachesdocs/technical-context/ARCHITECTURE_CHALLENGES.md— known pain points and what the team wants to improve
Run /engineer:discover alone if you just want context.md to have something to draw on quickly; run /bootstrap:tech-docs when you want the full "DNA" document written down. Running both is fine — /engineer:doctor reports both shapes present, it doesn't treat it as a conflict.
Step 6: the business side
claude "/bootstrap:business-docs [links to the product's docs/tickets, if you have them]"With existing material to mine (a README with a real product description, GitHub issues, marketing pages), this runs in Analysis mode: it researches the product, market, and customers, asks a round of clarifying questions, then writes:
docs/business-context/index.md— master indexdocs/business-context/CUSTOMER_PERSONAS.mddocs/business-context/CUSTOMER_JOURNEY.mddocs/business-context/PRODUCT_STRATEGY.mddocs/business-context/features/— one file per existing featuredocs/business-context/PRODUCT_METRICS.mddocs/business-context/COMPETITIVE_LANDSCAPE.mddocs/business-context/INDUSTRY_TRENDS.mddocs/business-context/SALES_PROCESS.md(if relevant)docs/business-context/MESSAGING_FRAMEWORK.mddocs/business-context/CUSTOMER_COMMUNICATION.md
If an "existing" repo turns out to have little or nothing to mine (a bare scaffold, a pre-launch idea), both bootstrap commands fall back to Collection mode automatically — same as a brand-new project.
Step 7: warm up and start the pipeline
claude "/warm-up"From here, CoDriDe treats an existing project exactly like a new one — /product:collect, /engineer:context, and the rest of the pipeline all draw on the master docs just generated.
We used to trust a reviewer's memory. Now we trust the master docs — and check every feature against them, before it's built and again before it ships.
CoDriDe treats two artifacts as load-bearing:
- Master docs are the project's DNA. A small set of living documents (business context + technical context) captures the decisions that matter — product strategy, personas, ADRs, conventions. Every feature gets checked against them before it's built (
/product:validate) and again before it ships (/engineer:validate, part of/engineer:pre-pr). - Every unit of work leaves a paper trail.
/engineer:contextand/engineer:architecturewritecontext.mdandarchitecture.md, and/engineer:planwrites a phasedplan.md, into.claude/work/<type>/<slug>/— and this isn't just for features.<type>follows Conventional Commits (feat,fix,docs,chore,refactor,test,perf,build,ci,style,revert), so a bug fix's work item lives at.claude/work/fix/<slug>/, matching the branch name. If work gets interrupted — a new chat, a different day, a different engineer — the next person reads its files and knows exactly where things stand.
Project management runs through GitHub Issues via the gh CLI — no separate PM tool to keep in sync by hand.
CoDriDe doesn't auto-detect complexity — you choose the entry point, and that choice is cheap to get "wrong" because both tracks are just commands:
flowchart LR
A[Change to make] -->|Small, well-understood| B[Engineering track]
A -->|Needs a spec first| C[Product track] --> B
A -->|Open-ended decision| D["/product:brainstorm"] --> E[wherever it leads]
A feature typically flows left to right: an idea gets collected and refined on the product side, then handed to the engineering side once there's a clear spec to build against.
| Agent | Responsibility | Trigger Condition |
|---|---|---|
branch-master-docs-checker |
Checks the branch against master docs | /engineer:validate (standalone or via /engineer:pre-pr) |
branch-code-reviewer |
Code quality, bugs, security, dependency audit | /engineer:review |
branch-documentation-writer |
Keeps user-facing docs (README, API reference, usage examples) in sync with code changes | /engineer:sync-docs |
branch-test-planner |
Finds missing test coverage, including BDD scenario gaps | /engineer:coverage |
adr-compliance-checker |
Validates code against the project's ADRs | /engineer:discover, /engineer:work |
github-project-sync |
Syncs feature docs with GitHub Issues | /product:sync-github |
python-developer |
Idiomatic Python implementation | On demand, non-trivial Python work |
typescript-developer |
Idiomatic TypeScript/JavaScript implementation | On demand, non-trivial TS/JS work |
These 8 are CoDriDe's portable core — unprefixed names. Anything created via /meta:create-agent is project-specific and gets a project- prefix instead (see Advanced Configuration) — that prefix is the only thing distinguishing the two, since .claude/agents/ doesn't support subdirectories.
.claude/commands/, .claude/agents/, CLAUDE.md, and .claude/rules/*.md are CoDriDe's canonical, hand-authored source — always maintained directly, never generated. /meta:generate-target <tool> (maintainer-side, run in this repo, never by someone adopting the framework) translates that source into another LLM CLI's own native format, written to that tool's own conventional path at repo root — never nested under a CoDriDe-specific folder, and always a full, clean overwrite so it can't silently drift out of sync with hand-edits made in between. /engineer:doctor flags a target as stale once .claude/ has changed since it was last generated.
Adopting CoDriDe for a tool other than Claude Code works exactly like Step 2 of setup — just copy that tool's generated output instead of .claude/. Most targets follow one .<tool>/ + <TOOL>.md pattern (e.g. .gemini/ and GEMINI.md for Gemini CLI); two don't — Codex CLI's generated root is .agents/ (+ AGENTS.md), following Codex's own naming convention rather than a .codex/ folder, and GitHub Copilot CLI's is .github/agents/ (+ .github/copilot-instructions.md), following GitHub's own convention rather than a .copilot/ folder. No Claude Code involved at any point for any of these adopters. Work-item folders (context.md/architecture.md/plan.md) are per-tool too, not shared — .claude/work/ for Claude Code, .gemini/work/ for Gemini CLI, .codex/work/ for Codex CLI, and .copilot/work/ for GitHub Copilot CLI — each matching the tool's own name rather than its output folder's name where those diverge (Codex, Copilot). An adopter's choice not to commit a given tool's copied folder(s) still covers that tool's work items — just double-check which folder(s) that means for whichever tool you're on, since it isn't always the one you copied.
Status: Claude Code, Gemini CLI, Codex CLI, and GitHub Copilot CLI are all supported today.
Commands are invoked as /<folder>:<file>, e.g. .claude/commands/product/spec.md → /product:spec. /warm-up lives at the top level, so it's just /warm-up. That's Claude Code's syntax — Gemini CLI uses the same /namespace:command convention; Codex CLI and GitHub Copilot CLI use flat names (product-spec, engineer-doctor) with no folder namespace. Each command's role is the same across all four tools; only the invocation syntax changes — see your CLI's guide in Multi-LLM Support.
Setup — /warm-up, /engineer:doctor, /engineer:discover
Loads both halves of the master docs — product (docs/business-context/) and engineering (docs/technical-context/) — plus the root README.md, so the session starts with the right context loaded. It reads index/entry-point files only, not everything they point to. If a piece doesn't exist yet, it says so and moves on.
- Usage:
/warm-up(project name is optional, only useful in a multi-project workspace) - Tips: run this at the start of any session where you'll touch product or architecture decisions. Skip it for a one-line bug fix.
A pre-flight health check, not a fix-it command: reports gh auth status, the repo's actual default branch, whether a test suite exists, the state of master docs, GitHub label taxonomy, and whether the repo is a monorepo — all in one pass, without changing anything.
- Usage:
/engineer:doctor - Tips: run it right after copying
.claude/into a project, whether that project is brand-new or has years of history — on an existing repo it's what surfaces "this isn'tmain, it'sdevelop" or "there's no test suite" before those assumptions break a command mid-pipeline instead of at the start.
Scans the codebase once (or incrementally) and writes docs/technical-context/project-briefing.md plus docs/technical-context/briefing/critical-rules.md, adrs-summary.md, and tech-stack.md. Also detects which domains are present — backend, frontend, mobile (React Native, Flutter, native iOS, native Android), not mutually exclusive — and writes backend-conventions.md/frontend-conventions.md/mobile-conventions.md for whichever were actually found. Infers architectural conventions and identifies the stack from the manifest file per domain — then runs adr-compliance-checker against the existing codebase, so onboarding an existing project surfaces where the code has already drifted from its own documented decisions.
- Usage:
/engineer:discover, or/engineer:discover --verbosefor a detailed run - Tips: write your ADRs before running this if you can — the more decisions are documented, the more
adr-compliance-checkerhas to check against, both here and again later during/engineer:work.
Bootstrapping master docs — /bootstrap:*
Generate the multi-file master-docs architecture from scratch. Use once per project, then maintain by hand (or via /engineer:sync-docs).
Generates the full technical-context architecture (project charter, ADRs, AI dev guide, codebase navigation, business logic, API spec, contributing guide, troubleshooting) under docs/technical-context/. Works two ways, same split as /bootstrap:business-docs: analysis mode analyzes the local codebase on its own (arguments only add material outside this repo); collection mode runs an architecture interview instead, for a brand-new project with no code yet — every planned decision comes back explicitly marked as planned, not implemented.
- Usage:
/bootstrap:tech-docs, or/bootstrap:tech-docs <links to repos/files to analyze>to include external material
Generates the full business-context architecture (personas, journey, voice of customer, product strategy, feature catalog, competitive landscape, sales/messaging guidance) under docs/business-context/. Works two ways: analysis mode mines material you point it at; collection mode runs a founder/PM interview instead, for a brand-new project with nothing to analyze yet.
- Usage:
/bootstrap:business-docs <links to product docs, support tickets, existing PRDs, etc.>, or with no arguments for collection mode. - Tips: in collection mode, everything generated is explicitly marked as an unvalidated hypothesis — re-run it (or use
/product:brainstorm) once real customers confirm or revise those assumptions.
Builds or refreshes an index.md pointing to every useful documentation file. Detects whether this is a single project or a multi-project docs meta-repo, and adapts accordingly.
- Usage:
/bootstrap:indexor/bootstrap:index <project-name>(meta-repo mode)
Product track — /product:*
Captures a raw idea or bug report as a GitHub issue, with just enough clarity to recall it later — no full spec yet.
- Usage:
/product:collect "users can't reset their password if their email has a plus-alias" - Tips: using Jira, Linear, Asana, Trello, Azure DevOps, or another external PM tool? Pasting the task's title/description as the argument text always works. Referencing just the ID (
/product:collect PROJ-123) can also work, but isn't a supported integration — it's entirely up to the model to infer that the ID refers to an external ticket and decide, on its own, to call some MCP tool connected in the session it judges capable of "resolving" that reference. Without that tool's MCP connected, or if the model doesn't make that inference, the ID is treated as literal text.
Turns a collected requirement into a structured WHY / WHAT / HOW document. Updates the issue or the given file directly (gh issue edit or a file edit) — doesn't create a new file.
- Usage:
/product:refine #42(a GitHub issue number) or/product:refine <path/to/file.md>
Validates one or more described features against the project's master docs, reporting what's aligned and what contradicts a specific master doc (with a citation).
- Usage:
/product:validate "add social login via Google and GitHub"— free text, not an issue ID; works even before an issue exists. - Tips: not to be confused with
/engineer:validate, which checks the branch after the fact — this one checks the idea, before anything is built.
Expands a validated requirement into a full PRD: product overview, functional requirements (numbered FR-01, FR-02, ...) with BDD acceptance criteria, non-functional requirements, UX and technical considerations, risks, constraints. Also saves docs/business-context/features/<slug>.md in the format /product:sync-github expects.
/product:spec itself already does, internally, what /product:refine and /product:validate do separately: its Step 1 confirms the requirement has enough WHY/WHAT/HOW (asking the user if it doesn't), and its Step 2 checks it against the project's master docs. That's why going straight from /product:collect to /product:spec is valid — a shortcut, not an error. Running the separate steps first still makes sense for bigger, riskier requirements, where it's worth having each check as an explicit human checkpoint (the issue documented by refine, the cited report from validate) before generating the full PRD.
- Usage:
/product:spec #42(issue number) or/product:spec "<requirement in free text>"
A structured, deliberately adversarial brainstorming session for open-ended product or business decisions — generates real alternatives, trade-off and risk matrices, and a grounded recommendation, then stops for human review.
- Usage:
/product:brainstorm "should we build a native mobile app or invest in the PWA?" - Tips: it's the heaviest command in the framework — reserve it for decisions with real alternatives worth weighing.
Creates a fully-specced GitHub issue directly from a task description, without the multi-step collect → refine → spec dialogue. Also saves docs/business-context/features/<slug>.md, same as /product:spec.
The data comes from two sources: the task description you pass as the argument, and the project's existing documentation (README.md + docs/), which it reads first to infer architecture, suggested libraries (prioritizing ones already used in the project), and affected components. "Without an interview" means it skips /product:refine's structured clarifying-question round — it still presents its understanding and asks for your confirmation before creating the issue, and only asks extra questions when something essential can't be inferred from the task + the docs.
- Usage:
/product:quick-spec "add rate limiting to the public API, 100 req/min per API key" - Tips: the more complete the project's master docs, the fewer clarifying questions it needs to ask — if the project doesn't have
docs/business-context//docs/technical-context/yet, expect more questions, or consider the staged pipeline (/product:collect→/product:refine→/product:spec) for tasks with real ambiguity. Same caveat as/product:collectabout referencing an external ticket ID (Jira, Linear, etc.) instead of pasting the description: it can work, but depends on the model inferring and calling a connected MCP tool on its own — not something the command guarantees.
Keeps docs/business-context/features/*.md in sync with this repo's GitHub Issues — creates missing issues, updates ones that drifted, flags orphans. Always previews the diff before writing anything.
- Usage:
/product:sync-github,/product:sync-github module=Billing, or/product:sync-github preview
Engineering track — /engineer:*
Kicks off a unit of work: an interview to build shared understanding, written to .claude/work/<type>/<slug>/context.md. First of a two-step pair with /engineer:architecture.
- Usage:
/engineer:context feat/csv-order-export— argument is<type>/<slug>, not the issue number; becomes.claude/work/feat/csv-order-export/context.md
Reads .claude/work/<type>/<slug>/context.md and designs the implementation, written to .claude/work/<type>/<slug>/architecture.md, with a mandatory consistency check between the two documents before you approve.
- Usage:
/engineer:architecture feat/csv-order-export→ writes.claude/work/feat/csv-order-export/architecture.md
Turns context.md + architecture.md into a phased .claude/work/<type>/<slug>/plan.md, each phase sized to roughly 2 hours of human work, resumable if interrupted.
- Usage:
/engineer:plan feat/csv-order-export→ writes.claude/work/feat/csv-order-export/plan.md
Executes the next phase of plan.md, keeps the GitHub issue's status label in sync in real time, and implements test-first against any BDD acceptance criteria.
- Usage:
/engineer:work .claude/work/feat/csv-order-export— the argument is the work item's folder path, not<type>/<slug>or the issue number
An orchestrator, not a check of its own: runs /engineer:validate and /engineer:review in parallel, then /engineer:sync-docs and /engineer:coverage sequentially — and helps you act on their combined feedback.
- Usage:
/engineer:pre-pr
One-line shortcuts that invoke branch-master-docs-checker / branch-code-reviewer / branch-documentation-writer / branch-test-planner directly — each also runs standalone, without the full /engineer:pre-pr sweep. Note the split: /engineer:validate checks the branch against the internal master docs (business/technical context, the project's "DNA"); /engineer:sync-docs updates the external, user-facing docs instead — README, API reference, usage examples, install/config guides — anything another developer or team would read to understand or integrate the project.
- Tips: run
/engineer:coverageright after a phase while the code is fresh; run/engineer:reviewmid-feature, not just before a PR.
Runs tests, commits, opens the PR, moves the GitHub issue to "in review", and triages automated code-review bot comments with you.
- Usage:
/engineer:pr
Bumps the project's semver version, detecting whether the project uses pyproject.toml, package.json, or both.
- Usage:
/engineer:bump
Drafts a new Architecture Decision Record under docs/technical-context/adr/, checking first for conflicts with or supersession of existing ADRs.
- Usage:
/engineer:adr "use event sourcing for the order aggregate"
Meta — /meta:create-agent, /meta:preferences, /meta:generate-target
Creates a new sub-agent under .claude/agents/, named project-<name>.md by default (see Advanced Configuration).
- Usage:
/meta:create-agent "an agent that audits our GraphQL schema for breaking changes before merge"→ createsproject-graphql-schema-auditor.md
Configures project-level preferences, always scoped to this project (never a machine-wide setting): what language docs/ and .claude/work/ artifacts get written in — not conversational language, which Claude already mirrors automatically — and whether Artifacts (claude.ai-hosted pages) may be published. Writes docs/PROJECT_PREFERENCES.md, a sibling to docs/business-context/ and docs/technical-context/ rather than nested inside either, since none of this is business/product content. /warm-up reads it every session; an Artifacts denial is also enforced via .claude/settings.local.json. Re-runnable anytime to change an answer.
- Usage:
/meta:preferences - Tips: run it right after
/engineer:doctoron a freshly adopted project./engineer:doctoritself only reports whether preferences are configured — it never writes them.
Translates CoDriDe's canonical .claude/ source into another LLM CLI's native format — see Multi-LLM Support. Maintainer-side only: run in this repo to produce a target's files, never by someone adopting the framework.
- Usage:
/meta:generate-target gemini(orcodex,copilot) - Tips: always a full, clean overwrite of that target's previously generated output — safe and expected to re-run anytime
.claude/changes./engineer:doctorflags when a target has drifted from the current source.
docs/
├── index.md # entry point across both contexts below — /bootstrap:index, single-project mode
│ # (distinct from business-context/index.md just below it)
├── PROJECT_PREFERENCES.md # docs/work language, Artifacts stance — /meta:preferences writes it,
│ # /warm-up reads it every session; not business/product content
├── business-context/ # master docs: strategy, personas, feature catalog
│ ├── index.md # entry point, generated by /bootstrap:business-docs
│ ├── features/ # one .md per feature — /product:spec or /product:quick-spec write it,
│ │ # /product:sync-github keeps it in sync with GitHub Issues
│ ├── brainstorm/ # /product:brainstorm session output
│ └── CUSTOMER_PERSONAS.md, PRODUCT_STRATEGY.md, COMPETITIVE_LANDSCAPE.md, ... (see /bootstrap:business-docs)
└── technical-context/ # shape depends on which command generated it:
├── project-briefing.md # /engineer:discover → compact briefing (+ briefing/*.md below)
├── briefing/ # critical-rules, adrs-summary, tech-stack, + backend/frontend/mobile-conventions
│ # (only the domains actually detected — not mutually exclusive)
├── index.md # /bootstrap:tech-docs → entry point for the fuller set below
├── adr/ # Architecture Decision Records
└── project_charter.md, CODEBASE_GUIDE.md, BUSINESS_LOGIC.md, API_SPECIFICATION.md, ...
.claude/
├── agents/ # the 8 agents above (+ project-*.md you add)
├── commands/ # engineer/, product/, bootstrap/, meta/, warm-up.md
├── work/<type>/<slug>/ # context.md, architecture.md, plan.md, and a conditional
│ # test-coverage-report.md (from /engineer:coverage) per work item
│ ├── feat/csv-order-export/ # e.g. a feature
│ └── fix/password-reset-plus-alias/ # e.g. a bug fix
├── rules/product-agent.md # always-on PM/architect persona
└── .generation-log.md # append-only manifest — /meta:generate-target writes it,
# /engineer:doctor reads it to flag stale targets;
# empty until the first target is generated
docs/technical-context/ normally has just one of the two shapes shown, not both. <type> in .claude/work/ and branch names follows Conventional Commits (feat, fix, docs, chore, refactor, test, perf, build, ci, style, revert).
docs/business-context/features/<slug>.md — the format /product:spec writes and /product:sync-github reads:
# [Feature Title]
**Status**: Planned
**Priority**: High
**Scope**: MVP
[1-2 paragraph product overview]
### FR-01: [Requirement title]
[Description]
**Acceptance criteria:**
```
Given ...
When ...
Then ...
```CoDriDe's core loop needs nothing beyond gh — no MCP server is required. Two are worth adding for specific, real gains:
- Context7 — up-to-date library/framework documentation lookup, scoped to the actual version in use. Wired directly into
python-developerandtypescript-developer's tool lists; they check the real dependency version first, then use Context7 if it's configured, orWebSearchif it isn't. - A Playwright MCP (e.g.
@playwright/mcp) — closes the loop on BDD acceptance criteria by letting an agent actually drive a browser through aGiven/When/Thenscenario. Only relevant for projects with a web UI.
- Let
/engineer:context,/engineer:architecture,/engineer:plan, and/product:brainstormpause at their checkpoints — don't push past them just because the answer feels obvious. - Run
/engineer:discoverahead of time, not mid-feature, so/engineer:contexthas a briefing ready to load selectively. - Treat a
/product:validateorbranch-master-docs-checkerconflict as a real signal to stop and discuss, not noise to click through. - Extend the agent roster with
/meta:create-agentfor anything project- or stack-specific — it prefixesproject-*automatically. - Run
/engineer:reviewand/engineer:coveragemid-feature, not only at/engineer:pre-prtime — catching an issue earlier is cheaper.
- Running the full product → engineering pipeline for a one-line fix (go straight to a branch +
/engineer:pre-pr). - Skipping the cross-consistency check
/engineer:architectureruns betweencontext.mdandarchitecture.md. - Editing one of the 8 shipped agents directly instead of adding a
project-*one. - Managing a separate GitHub token or MCP server for issue tracking —
gh auth statusis the only credential this framework needs. - Leaving
docs/business-context/features/unpopulated and expecting/product:sync-githubto have anything to sync.
flowchart LR
A["/warm-up"] --> B
subgraph B["Product track"]
direction LR
B1[collect] --> B2[refine] --> B3[validate] --> B4[spec]
end
B --> C
subgraph C["Engineering track"]
direction LR
C1[context] --> C2[architecture] --> C3[plan] --> C4[work]
end
C --> D["/engineer:pre-pr<br/>4 checks, 2 parallel + 2 sequential"]
D --> E["/engineer:pr<br/>commits, opens PR, moves issue"]
B -.writes.-> BN["docs/business-context/features/<slug>.md<br/>(FR-XX + BDD)"]
C -.writes.-> CN[".claude/work/<type>/<slug>/<br/>context.md → architecture.md → plan.md"]
Acceptance criteria are written once and consumed three times, without being retyped:
flowchart TD
A["/product:spec writes Given/When/Then per FR-XX"]
B["/engineer:context carries them into context.md verbatim"]
C["/engineer:work implements test-first against them (red → green → refactor)"]
D["/engineer:coverage (branch-test-planner) verifies every scenario has a matching test"]
A --> B --> C --> D
flowchart LR
subgraph Step1["Step 1 (parallel, read-only)"]
direction TB
V["/engineer:validate"]
R["/engineer:review"]
end
subgraph Step2["Step 2 (sequential, writes)"]
direction TB
S["/engineer:sync-docs"] --> Co["/engineer:coverage"]
end
Step1 --> Step2
Validate and review don't depend on each other's output and touch nothing on disk, so they run concurrently. Sync-docs and coverage both write, so they run one after the other, after the read-only pair finishes.
context.md↔architecture.md:/engineer:architectureruns a mandatory cross-check before you approve — catches "context.md says modify X, architecture.md says delete X" before it becomes a real bug.- Branch ↔ master docs:
branch-master-docs-checker(/engineer:validate) checks the branch's actual changes against the master docs, independent of what was planned. - ADRs ↔ code:
adr-compliance-checkerruns during/engineer:discoverand/engineer:work, advisory by default — it suggests fixes rather than blocking, unless a project explicitly configures a rule as strict.
Extend CoDriDe with project- or stack-specific agents via /meta:create-agent (a NestJS specialist, a Terraform reviewer, whatever your project needs) — never edit the 8 shipped agents directly.
.claude/agents/ is a flat namespace (Claude Code doesn't discover agents in subdirectories), so naming does the job a folder would: every agent /meta:create-agent creates is named project-<name>.md by default (e.g. project-notion-specialist.md). Give it a plain-language description — in any language — and it normalizes the name itself (translate → condense to 2-4 words → kebab-case → prefix).
---
name: project-[agent-name]
description: [clear description of the agent's purpose]
tools: [minimal tool list — Read/Glob/Grep/Bash for a checker, add Write/Edit only if it modifies files]
---
[System prompt: role, step-by-step process, constraints, output format]Add custom commands under .claude/commands/<namespace>/<command>.md — the folder becomes the namespace (.claude/commands/product/spec.md → /product:spec).
---
description: [one-line description shown in the / picker]
argument-hint: [<required> or [optional] — matches the bracket style]
---
[Instructions for what this command does, step by step]
#$ARGUMENTS.claude/settings.local.json holds machine-local permissions (which Bash/WebSearch calls are pre-approved) — it's gitignored by convention, not meant to be shared. Keep it minimal (git *, gh * cover almost everything this framework needs).
The same file's permissions.deny array is where /meta:preferences writes when you opt out of Artifacts — don't hand-edit this unless you're changing what that command already set. Since this file is machine-local, the shared intent lives in docs/PROJECT_PREFERENCES.md instead (versioned, read by every /warm-up) — a teammate on a different machine still needs to run /meta:preferences themselves (or add the rule by hand) to get the same hard enforcement locally.
(Claude Code syntax — see your CLI's guide in Multi-LLM Support for the equivalent syntax on Gemini CLI, Codex CLI, or GitHub Copilot CLI)
claude "/product:collect customers want to export their order history as CSV"
# → creates GitHub issue #42
claude "/product:refine #42"
# → issue #42 rewritten as WHY / WHAT / HOW
claude "/product:validate CSV export of order history, issue #42"
# → confirms this doesn't violate any master doc (free text — not the issue ID as a structured argument)
claude "/product:spec #42"
# → full PRD with FR-01, FR-02... and Given/When/Then acceptance criteria;
# also writes docs/business-context/features/csv-order-export.md
claude "/engineer:context feat/csv-order-export"
# → interview → .claude/work/feat/csv-order-export/context.md (the argument is now <type>/<slug>, not the issue)
claude "/engineer:architecture feat/csv-order-export"
# → design → .claude/work/feat/csv-order-export/architecture.md, cross-checked against context.md
claude "/engineer:plan feat/csv-order-export"
# → .claude/work/feat/csv-order-export/plan.md (phased)
claude "/engineer:work .claude/work/feat/csv-order-export"
# → implements phase by phase, test-first against the acceptance criteria;
# syncs issue #42 to "in progress"
claude "/engineer:pre-pr"
# → validate + review run in parallel, then sync-docs + coverage
claude "/engineer:pr"
# → commits, opens the PR, moves issue #42 to "in review"claude "/product:quick-spec add rate limiting to the public API, 100 req/min per API key"
# → fully-specced GitHub issue, no interview needed
claude "/engineer:context fix/api-rate-limiting"
claude "/engineer:architecture fix/api-rate-limiting"
claude "/engineer:plan fix/api-rate-limiting"
claude "/engineer:work .claude/work/fix/api-rate-limiting"
claude "/engineer:pre-pr"
claude "/engineer:pr"A: Claude Code without CoDriDe still writes good code, but every session re-derives the project's conventions from scratch, and there's nothing durable to check a change against. CoDriDe adds master docs (a persistent source of truth), a type/slug work-item convention (so interrupted work resumes instead of restarting), and a fixed set of checks (/engineer:pre-pr) that run the same way every time.
A: Yes. /engineer:context and /engineer:architecture work without them; they just have less context to draw on. Run /bootstrap:business-docs and /bootstrap:tech-docs whenever you're ready — both work with nothing to analyze yet, via their interview-driven collection modes.
A: The product/engineering pipeline is built around gh, and github-project-sync is one of the 8 core agents. If your project uses a different tracker, you'd need a project-* agent (via /meta:create-agent) to replace github-project-sync's role — the rest of the pipeline (master docs, work items, BDD/TDD loop) doesn't depend on GitHub specifically.
A: Run it directly — /engineer:validate, /engineer:review, /engineer:sync-docs, and /engineer:coverage are all standalone commands. /engineer:pre-pr is a convenience orchestrator, not a requirement.
A: /meta:create-agent — describe what you need in plain language, it proposes a project-*-prefixed name and a minimal tool set, and you confirm before it's created.
Q: How do I stop Claude from publishing Artifacts, or set the language for docs//.claude/work/ files?
A: /meta:preferences — asks once (re-runnable anytime to change an answer), always scoped to the current project. Writes docs/PROJECT_PREFERENCES.md, read by every /warm-up; an Artifacts denial is also enforced in .claude/settings.local.json. This doesn't touch conversational language — Claude already mirrors whatever language you write in.
A: Yes — see Multi-LLM Support for what each target looks like on disk. .claude/ stays the canonical source either way; each other tool's own native files are generated from it, and an adopter copies those instead of .claude/, with no Claude Code involved on their end.
Contributions are welcome — this framework improves the same way any CoDriDe-managed project does: through the pipeline itself.
- Fork the project and create a branch named
type/slug(e.g.fix/adr-numbering,feat/rust-developer-agent), matching the Conventional Commits types CoDriDe's own work items use. - Make your change — if you're touching
.claude/commands/or.claude/agents/, keep the existing tone (direct, no fluff) and the minimal-tools convention. - Update
README.md/CLAUDE.mdif the change affects the pipeline, command list, or agent roster — they're expected to stay accurate, not just the command files themselves. - Open a PR describing what changed and why.
git clone https://github.com/your-username/codride.git
cd codride
git checkout -b feat/your-feature-name
# ... make your changes ...
git add <specific files>
git commit -m "add your feature description"
git push origin feat/your-feature-name- 🐛 Fixes: broken cross-references, inconsistent naming, stale documentation
- ✨ New agents/commands: following the minimal-tools, single-responsibility conventions already in place
- 📚 Documentation: clarifying gaps, adding examples
- 🌐 Framework/language coverage: a generic (not stack-locked) implementer agent for a language CoDriDe doesn't cover yet
This project is open source under the MIT License.
Originated on Claude Code by Anthropic — CoDriDe's canonical source is still hand-authored in that format — and today also natively available on Gemini CLI, Codex CLI, and GitHub Copilot CLI.
- CLI documentation: Claude Code • Gemini CLI • Codex CLI • GitHub Copilot CLI
- Issue reports: GitHub Issues
- Conventional Commits (the
type/slugconvention behind work items and branches): conventionalcommits.org
If CoDriDe helps you, please give it a ⭐️
Made with ❤️ by Edilson Silva