╔═══════════════════════════════════════════════════════════╗
  ║                                                           ║
  ║   ████  █████ █   █  ████  ███  ████  █████ █████ █   █     ║
  ║   █   █ █     █   █ █     █   █ █   █   █   █      █ █      ║
  ║   █   █ ███   █   █ █     █   █ ████    █   ███     █       ║
  ║   █   █ █      █ █  █     █   █ █  █    █   █      █ █      ║
  ║   ████  █████   █    ████  ███  █   █   █   █████ █   █     ║
  ║                                                           ║
  ║   AI workflow orchestrator for Claude Code                ║
  ║                                                           ║
  ╚═══════════════════════════════════════════════════════════╝

Devcortex turns Claude Code into a senior engineering team. It orchestrates a team of specialized AI agents through a structured lifecycle — research → plan → build → review → verify — and a hard pipeline gate keeps Claude from skipping steps. You ship production-grade code, not demo-ware.

42 commands · 13 core + 22 specialist agents · 10 hooks · parallel multi-task · activity ledger · zero dependencies

npx devcortex init

Contents

• Why Devcortex
• Quick Start
• Work Hierarchy — quick · task · story · project
• Parallel Multi-Task & Activity Ledger
• How It Works — agents, state machine, enforcement, stack intelligence
• Quality Gates — research, plans, tests, execution audit
• Operating the Pipeline — auto mode, dashboard, cost, review
• Command Reference
• Plugins & Configuration
• Tutorial
• Architecture
• Requirements & License

Why Devcortex

Claude Code is powerful but unstructured. You start building, lose context mid-session, forget what was decided, skip verification, and end up with code that demos well but breaks in production. There's no audit trail and nothing stops a step from being skipped.

Devcortex adds structure without friction. Every step produces artifacts. Every decision is tracked. Every phase is verified before the next begins. And a four-layer gate makes code review non-bypassable.

/devcortex:new-project  →  Detects your stack, maps your codebase
/devcortex:story        →  Researches the domain, builds a phased roadmap
/devcortex:discuss      →  Captures architectural decisions before coding
/devcortex:plan         →  Produces verified execution plans with TDD
/devcortex:execute      →  Builds with per-task commits and deviation handling
/devcortex:review       →  Two-stage review: spec compliance + code quality
/devcortex:verify       →  3-level verification against must-haves
/devcortex:complete     →  Advances to the next phase with an audit trail

Quick Start

npx devcortex init

That's it. Devcortex detects your project (Laravel, Next.js, Django, FastAPI, Flask, Go, Rails — 15+ frameworks), registers its agents, installs the pipeline hooks, generates framework-specific stack commands, and is ready to drive.

/devcortex:new-project           # Detect stack, map codebase
/devcortex:story "v1.0 MVP"      # Start a milestone with research + roadmap
/devcortex:progress              # Where am I? What's next?

Requirements: Node.js 22+ and Claude Code. Zero runtime dependencies.

Work Hierarchy

Four levels of work, from lightweight to comprehensive — pick the ceremony that fits the job:

| Level | Command | Pipeline | Duration | |-------|---------|----------|----------| | Quick | /devcortex:quick "fix bug" | plan → execute → review → commit | Minutes | | Task | /devcortex:new-task "add Stripe" | discuss → plan → execute → review → verify | Hours | | Story | /devcortex:story "v1.0 MVP" | research → requirements → roadmap → phases | Days/Weeks | | Project | /devcortex:new-project | detect → map → suggest next step | One-time |

Quick tasks — skip the ceremony

/devcortex:quick "fix the login redirect bug"        # plan → execute → review → commit
/devcortex:quick --full "add rate limiting to API"   # + verification gate

Significant tasks — full pipeline

/devcortex:new-task "add payment integration with Stripe"
/devcortex:new-task --light "fix auth redirect"      # skip discuss + verify (research + review still mandatory)
/devcortex:new-task --continue                       # resume the focused task
/devcortex:new-task --continue 2                     # advance a specific task by number
/devcortex:new-task --promote 1                      # promote a task into a roadmap phase

Stories — organize significant work

A story is a milestone. Devcortex researches the domain with parallel agents, generates requirements with REQ-IDs, builds a phased roadmap, then guides execution phase by phase.

/devcortex:story "v1.0 MVP"
/devcortex:story --continue        # resume current step
/devcortex:story --list            # list all stories
/devcortex:story --status          # show progress
/devcortex:story --complete        # complete story, bump version

Parallel Multi-Task

Devcortex runs multiple tasks at once, each isolated in its own git worktree + branch (devcortex/task-NN-slug) so concurrent executors never collide on the same files. Claude drives each task's pipeline in a background Task; you switch focus, watch progress, and merge as each lands.

/devcortex:parallel "add rate limiting" "fix CSV export" "upgrade logger"  # fan out, one worktree each
/devcortex:new-task "refactor auth" --parallel    # opt a single task into its own worktree
/devcortex:new-task --switch 3                     # change which task bare --continue targets
/devcortex:new-task --status                       # ledger-backed digest of every active task
/devcortex:new-task --merge 3                      # merge task 3's branch back, remove its worktree

Sequential (non---parallel) tasks keep the original one-at-a-time guard — they share the main working tree, so only one runs at a time. Parallel isolation requires a git repository.

Activity ledger — efficient session resume

Every task step is recorded to a cross-session activity ledger, scoped by project path + task. A fresh session reads a compact digest — last step reached, files touched, open failures, artifacts — instead of re-scanning every .devcortex/ artifact, so context is spent on the work, not on rediscovery.

/devcortex:new-task --status     # "Task #2 — last step: execute, 4 files touched, 1 open failure …"
/devcortex:ledger --recent       # inspect activity (--task N, --projects, --sql "SELECT …")

The ledger stores summaries and artifact pointers, never full transcripts — the heavy content stays in the .md artifacts on disk. A single global store at ~/.devcortex/ spans every project.

Dual backend — zero-dependency by design

The ledger auto-selects its storage to preserve Devcortex's zero-dependency promise, and the rest of the codebase only ever calls record() / resume() regardless of which is live:

| Backend | When it's used | Properties | |---------|----------------|------------| | node:sqlite | Node ≥ 23.4 (unflagged), or 22.5+ with --experimental-sqlite | Indexed, WAL + busy_timeout — multiple parallel task processes write concurrently without contention | | JSONL fallback | older / flagged Node | Append-only ledger.jsonl with a bounded reverse scan (last 5 000 lines) |

The ledger never throws — on any failure it degrades to a no-op so recording is always safe to call. It's an optimization, not a hard dependency of the pipeline.

Schema (SQLite backend)

-- activity: one row per subagent step
CREATE TABLE activity (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  project     TEXT NOT NULL,        -- realpath of the project (the scope key)
  task        INTEGER,              -- task number, or NULL for phase-level work
  phase       TEXT,
  agent       TEXT,                 -- which specialist ran (e.g. devcortex-executor)
  step        TEXT,                 -- discuss | plan | execute | review | verify …
  action      TEXT,
  files       TEXT,                 -- JSON array of touched paths
  summary     TEXT,
  tokens_in   INTEGER DEFAULT 0,
  tokens_out  INTEGER DEFAULT 0,
  status      TEXT,                 -- ok | fail | error | stuck …
  ts          TEXT NOT NULL         -- ISO-8601
);
CREATE INDEX idx_activity_project_task ON activity(project, task);

-- artifacts: pointers to the .md outputs each step produced
CREATE TABLE artifacts (
  id       INTEGER PRIMARY KEY AUTOINCREMENT,
  project  TEXT NOT NULL,
  task     INTEGER,
  kind     TEXT,                    -- research | plan | summary | verification | context
  path     TEXT,
  digest   TEXT,
  ts       TEXT NOT NULL,
  UNIQUE(project, task, kind, path)
);

-- meta: schema versioning
CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT);

The JSONL fallback mirrors these rows as newline-delimited JSON in ledger.jsonl (+ ledger-artifacts.jsonl).

Resume digest

resume() folds a task's timeline into a compact object — lastStep, lastAgent, ordered steps, deduped filesTouched, open failures, artifacts, event count and token totals — which renderDigest() turns into a markdown block injected into a fresh session.

Environment variables

| Variable | Effect | |----------|--------| | DEVCORTEX_LEDGER_DIR | Override the store location (default ~/.devcortex/; mainly for tests) | | DEVCORTEX_LEDGER_BACKEND=jsonl | Force the JSONL backend even when node:sqlite is available |

Read-only SQL: /devcortex:ledger --sql (and the raw query API) reject anything that isn't a SELECT — no writes through the query path.

How It Works

A team of specialist agents

Devcortex doesn't treat Claude as a single generalist — it orchestrates 13 core agents, each with a focused role:

| Agent | Role | What it does | |-------|------|--------------| | Researcher | Investigation | Analyzes technology, architecture, security, testing | | Synthesizer | Consolidation | Merges parallel research into actionable recommendations | | Planner | Architecture | Creates execution plans with dependency graphs and wave assignments | | Checker | Validation | Validates plans across 8 quality dimensions | | Executor | Implementation | Builds with TDD, atomic commits, and a checkpoint protocol | | Reviewer | Code quality | Reviews for DRY, over-engineering, framework best practices | | Spec Reviewer | Compliance | Verifies the implementation matches plan requirements exactly | | Verifier | Verification | 3-level depth checks: exists, substantive, wired | | Debugger | Debugging | 4-phase scientific method with hypothesis tracking | | Mapper | Analysis | Deep codebase analysis (stack, architecture, quality) | | Test Generator | Testing | Generates tests from plan requirements and implementation summaries | | Requirements Generator | Requirements | Structured requirements with acceptance criteria from research | | Roadmap Architect | Roadmap | Strategically-phased roadmap with dependency analysis |

On top of these, Devcortex generates up to 22 stack-specific specialist agents for your framework (see Stack Intelligence).

Deterministic state machine

Progress runs through a state machine with 21 statuses and strict transition rules:

pending → discussing → discussed → planning → planned → executing → executed
                                                            ↓
                                  reviewing → reviewed → verifying → verified → complete

Every command knows what comes next, and /devcortex:progress always points to the right step. Dangerous regressions (e.g. verified back to discussing) are hard-blocked at the FSM level.

Pipeline enforcement — four-layer defense

Devcortex doesn't just suggest the next step — it enforces it:

1. Prompt injection — user-prompt-submit.sh injects <HARD-GATE> reminders when review is pending
2. CLI gates — requirePassedReview() blocks completion without status: passed in REVIEW.md — no --force bypass
3. Git commit hook — pre-tool-use.sh blocks git commit during post-execution phases without a passed review
4. State machine — the executed → verifying shortcut is removed; the review step cannot be skipped

Code review is mandatory in every pipeline (quick, light, standard, story). Claude cannot bypass it.

Stack Intelligence

Devcortex auto-detects your stack and generates technology-specific specialist agents:

• 9 frameworks with specialist agents — Laravel (Eloquent Expert, Artisan Specialist), Next.js (App Router Expert, RSC Specialist), Django (ORM Expert, DRF Specialist), FastAPI, React Native (Navigation Expert, Expo Specialist), NestJS, Vue.js, Express, SvelteKit
• 15+ frameworks detected — also Flask, Rails, Flutter, Spring Boot, Astro, and more
• 3-layer expertise — static patterns + specialist agents + Context7 live documentation
• Infrastructure detection — Docker, CI/CD, monorepo tools, Python ecosystem
• Auto-generated /stack:* commands — e.g. /stack:migrate, /stack:test

/devcortex:enrich                  # generate specialist agents + stack profile (Context7 docs)
/devcortex:detect                  # re-scan stack and infrastructure
/devcortex:detect --json           # machine-readable detection output

Quality Gates

Devcortex scores work at each stage and sends anything below threshold back for another pass.

Deep research gate

Research depth is scored on 7 dimensions (word depth, section structure, version specificity, source credibility, risk awareness, actionable recommendations, code examples) before planning is allowed:

| Profile | Threshold | For | |---------|-----------|-----| | quick | 25 | bug fixes, small changes | | standard | 45 | features, refactors | | deep | 65 | major features, migrations, security |

Executors can trigger focused micro-research mid-task via the devcortex-researcher agent. Shallow analysis never reaches planning.

Plan quality scoring

Plans are scored on 6 dimensions before execution; cross-plan analysis flags files touched by multiple plans (merge-conflict risk):

| Dimension | Weight | Checks | |-----------|--------|--------| | Coverage | 20 | Are all requirements addressed? | | Task Completeness | 20 | Do tasks have behavior, action, verify, done? | | Dependency Soundness | 15 | Are file dependencies consistent? | | TDD Presence | 15 | Do tasks specify test behaviors? | | Scope Control | 15 | Within bounds (≤8 files, 2–4 tasks)? | | Specificity | 15 | Are file paths explicit, not vague? |

Closed-loop test feedback

The executor reads live test status from .devcortex/.test-bridge.json and reacts:

| Status | Failures | Action | |--------|----------|--------| | all-passing | 0 | continue | | minor-failures | <20% | continue with caution | | concerning | 20–50% | review failures | | critical | >50% | STOP and fix |

Post-execution audit

Before a phase completes, an execution audit scores the result: plan completion (30%), self-check passed (25%), file existence (25%), must-haves addressed (20%).

Wave-aware execution

Plans tagged wave: N in frontmatter are grouped. When a wave holds multiple independent plans, execute fans them out: it builds a full executor prompt per plan, isolates each in its own git worktree (default), and emits an explicit orchestration contract so all executors spawn in a single turn and run concurrently — instead of dripping one plan per invocation. A join step then merges each worktree, spot-checks each plan, records per-plan pass/fail to wave-status-{W}.json, and re-queues only the failures.

/devcortex:execute                       # wave-aware: parallel plans fan out into concurrent executors
/devcortex:execute --wave-join 1         # merge + spot-check + advance after a parallel wave finishes
/devcortex:execute --no-wave-isolation   # run parallel plans in the shared tree (no per-plan worktree)
/devcortex:execute --worktree            # single-plan isolated worktree branch, merge on success

The wave manifest is cached per phase (.manifest.json, keyed by file mtimes) so plan/wave discovery no longer re-reads every PLAN body on each command.

Operating the Pipeline

Auto mode

/devcortex:auto                    # autonomous execution across phases
/devcortex:auto --dry-run          # preview the runbook without executing
/devcortex:auto --phase 3          # start from a specific phase
/devcortex:auto --stop             # stop auto mode, release the lock

Auto mode chains discuss → plan → execute → review → verify → complete → next phase, with budget limits and cost projection, stuck detection and timeout tiers, an error-recovery decision tree, and loop detection (same step fails 3× → stop).

Two-stage review

/devcortex:review                  # both passes
/devcortex:review --spec-only      # does the implementation match the plan?
/devcortex:review --quality-only   # DRY, patterns, best practices

• Pass 1 — Spec compliance: the spec-reviewer extracts every must_have from the plans and verifies each against the implementation → SPEC-REVIEW.md (PASS/FAIL/PARTIAL per requirement).
• Pass 2 — Code quality: the reviewer checks DRY violations, over-engineering, anti-patterns, framework best practices → REVIEW.md.

Dashboard & observability

/devcortex:dashboard               # TUI dashboard
/devcortex:dashboard --browser     # web dashboard (live WebSocket updates)
/devcortex:dashboard --watch       # auto-refresh TUI every 3s
/devcortex:dashboard --json        # machine-readable output

Shows phase progress, cost tracking, timeout status, lock state, and recent events.

Cost tracking

/devcortex:progress --cost                       # budget status
/devcortex:config set budget.ceiling_usd 50      # spending ceiling
/devcortex:config set budget.mode hard-stop      # warn | pause | hard-stop

Stuck detection

| Tier | Default | What happens | |------|---------|--------------| | Soft | 20 min | "Consider wrapping up" | | Idle | 5 min no progress | "Agent may be stuck" | | Hard | 45 min | "Commit WIP and stop" |

Session management

/devcortex:pause                   # save session state for later
/devcortex:resume                  # restore session context
/devcortex:recover                 # detect and recover from crashes
/devcortex:health                  # self-diagnosis and auto-repair

Devcortex handles context-window pressure, session crashes, and stale locks automatically; the bootstrap.sh hook restores context on every new session.

Gates & error handling

Errors return structured envelopes with a recovery hint:

{
  "ok": false,
  "error": {
    "code": "PHASE_INVALID_STATUS",
    "message": "Invalid phase status: 'foo'",
    "recovery": "Use --force flag to override"
  }
}

--force bypasses only phase-order validation and the research gate — it cannot bypass the review or verify gates:

devcortex execute --force          # skip phase-order validation
devcortex plan --force             # skip the research gate

Command Reference

Setup

| Command | Description | |---------|-------------| | /devcortex:init | Initialize devcortex in the current project | | /devcortex:new-project | Detect project, map codebase, suggest next step | | /devcortex:detect | Re-scan stack, framework, and infrastructure | | /devcortex:enrich | Generate specialist agents + stack profile (Context7 docs) | | /devcortex:update | Update devcortex to the latest version | | /devcortex:upgrade | Version upgrade with hook migration |

Lifecycle

| Command | Description | |---------|-------------| | /devcortex:story | Start a milestone with research, requirements, roadmap | | /devcortex:discuss | Capture architectural decisions before coding | | /devcortex:assumptions | Surface hidden assumptions before planning | | /devcortex:plan | Create verified execution plans with TDD | | /devcortex:execute | Build per plans with atomic commits (--worktree for isolation) | | /devcortex:review | Two-stage review: spec compliance + code quality | | /devcortex:verify | 3-level verification against must-haves | | /devcortex:complete | Mark phase/milestone done, advance | | /devcortex:auto | Autonomous execution across phases |

Tasks

| Command | Description | |---------|-------------| | /devcortex:quick | Quick task — skip the ceremony | | /devcortex:new-task | Significant task — full pipeline (--parallel, --switch, --merge, --status) | | /devcortex:parallel | Run several tasks concurrently, each in its own git worktree | | /devcortex:add-tests | Generate tests from plan requirements | | /devcortex:todo | Extract and track TODOs from the codebase |

Phase Management

| Command | Description | |---------|-------------| | /devcortex:phase | List, peek, remove, reorder phases | | /devcortex:audit | Integration + milestone audit (--auto-fix closes gaps) | | /devcortex:uat | User Acceptance Testing — conversational criteria verification | | /devcortex:ship | Generate a PR description from verified phase artifacts |

Session

| Command | Description | |---------|-------------| | /devcortex:progress | Current status and next action | | /devcortex:pause | Save session for later | | /devcortex:resume | Restore session context | | /devcortex:recover | Detect and recover from crashes | | /devcortex:health | Self-diagnosis and auto-repair | | /devcortex:dashboard | Live monitoring dashboard (--browser, --watch) |

Tools

| Command | Description | |---------|-------------| | /devcortex:storm | Real-time brainstorming server (WebSocket) | | /devcortex:design | Collaborative design server — component canvas (WebSocket) | | /devcortex:adr | Architecture Decision Records — auto-created from discussions | | /devcortex:map | Deep codebase analysis (stack, architecture, quality) | | /devcortex:debug | Standalone debugging — 4-phase scientific method | | /devcortex:config | 47 settings across 10 categories | | /devcortex:ledger | Inspect the activity ledger (--recent, --task N, --projects, --sql) | | /devcortex:remove | Remove a phase or task |

Plugins & Configuration

Plugins

Extend Devcortex with custom commands, agents, and hooks:

.devcortex/plugins/
└── my-plugin/
    ├── plugin.json            # { name, version, commands, agents, hooks }
    ├── commands/
    │   └── my-command.cjs     # custom command handler
    └── templates/
        └── my-agent.md        # custom agent template

Plugin commands are namespaced (my-plugin:my-command) and auto-registered in the command and agent registries.

Configuration

Three model profiles trade quality for cost:

/devcortex:config set agents.profile quality     # best models everywhere
/devcortex:config set agents.profile balanced    # quality for planning, efficient for checking
/devcortex:config set agents.profile budget      # minimize token cost

Key settings:

/devcortex:config set mode interactive           # ask before major decisions
/devcortex:config set mode auto                  # full autonomy
/devcortex:config set depth thorough             # deep verification
/devcortex:config set enforcement.level hard     # strict pipeline enforcement

Portable across projects:

/devcortex:config export > devcortex-config.json
/devcortex:config import devcortex-config.json

Tutorial: Build Your First Feature

# 1. Initialize
npx devcortex init
#   [devcortex] Created .devcortex/ directory
#   [devcortex] Registered SessionStart hook + commands
#   [devcortex] Generated 3 stack commands for Next.js

# 2. Detect & map — stack, infrastructure, codebase structure
/devcortex:new-project

# 3. Start a story — parallel research → requirements → phased roadmap
/devcortex:story "v1.0 User Authentication"

# 4. Surface assumptions — approach, dependencies, scope, risks
/devcortex:assumptions

# 5. Discuss decisions — "JWT or session-based? Token expiry?" → CONTEXT.md
/devcortex:discuss

# 6. Plan — PLAN-01.md with tasks, dependencies, must_haves; checker validates
/devcortex:plan

# 7. Execute — per-task commits, SUMMARY-01.md documents what was done
/devcortex:execute

# 8. Review — spec compliance + code quality → SPEC-REVIEW.md + REVIEW.md
/devcortex:review

# 9. Verify — exists → substantive → wired → VERIFICATION.md
/devcortex:verify

# 10. Complete — mark done, advance; /devcortex:progress shows what's next
/devcortex:complete

┌─────────────┐   ┌───────────┐   ┌─────────────┐
│ new-project │──>│   story   │──>│ assumptions │
└─────────────┘   └───────────┘   └──────┬──────┘
                                         │
                                  ┌──────▼──────┐
                                  │   discuss   │
                                  └──────┬──────┘
                                         │
            ┌──────────┐         ┌──────▼──────┐
            │ complete │<────────│    plan     │
            └────┬─────┘         └──────┬──────┘
                 │                      │
          ┌──────▼──────┐        ┌──────▼──────┐
          │   verify    │<───────│   execute   │
          └──────┬──────┘        └──────┬──────┘
                 │                      │
                 │               ┌──────▼──────┐
                 └───────────────│   review    │
                                 └─────────────┘

Architecture

Modular state engine

| Module | Responsibility | |--------|----------------| | state-io.cjs | Atomic read/write with crash protection | | state-migration.cjs | Schema versioning and additive migrations | | state-transitions.cjs | Phase status validation with transition rules | | state-md.cjs | Human-readable STATE.md generation | | state-defaults.cjs | Default state creation and constants | | session-memory.cjs | Semantic memory: decisions, entities, patterns | | research-scorer.cjs / research-gate.cjs | Research quality scoring + depth gate | | plan-scorer.cjs | 6-dimension plan quality scoring | | test-feedback.cjs | Closed-loop test result analysis | | wave-planner.cjs | Wave-aware parallel execution planner | | execution-audit.cjs | Post-execution quality gate | | task-registry.cjs | Atomic (O_EXCL lock) concurrency-safe task registry | | ledger.cjs | Cross-session activity ledger (node:sqlite / JSONL) |

Commands declare a handler field in the registry and the CLI dispatches directly to the handler module — 42 commands across 6 categories. Devcortex is Claude Code-exclusive, integrating via settings.json hooks and shell scripts.

Project structure

.devcortex/                      # Devcortex state directory
├── devcortex.json               # state machine + configuration
├── STATE.md                     # human-readable state summary
├── detection.json               # stack detection cache
├── REQUIREMENTS.md              # requirements with REQ-IDs
├── ROADMAP.md                   # phased execution roadmap
├── metrics.json                 # cost tracking ledger
├── phases/                      # phase artifacts
│   └── 01-setup/
│       ├── PLAN-01.md           # execution plan
│       ├── SUMMARY-01.md        # execution results
│       ├── SPEC-REVIEW.md       # spec compliance review
│       ├── REVIEW.md            # code quality review
│       └── VERIFICATION.md      # verification results
├── stories/                     # milestone archives
├── designs/                     # design server outputs
├── plugins/                     # installed plugins
├── debug/                       # debug sessions
├── logs/                        # JSONL event logs
└── audits/                      # audit reports

Zero dependencies

Devcortex is a single npm package with zero runtime dependencies — just Node.js 22+. No supply-chain risk, no transitive vulnerabilities, no node_modules bloat.

{ "dependencies": {} }

Requirements

• Node.js 22+
• Claude Code (Anthropic's CLI)

License

MIT © Umutcan Güngörmüş