Task planning, development and QA workflows for Claude Code and Codex, stored in Markdown files.
A PM session records tasks and acceptance criteria, requests approval, and assigns work to Developer and QA roles. QA runs checks separately. Saved task files let a new session review the previous state and continue.
The workflow covers:
| Problem | What Project OS does |
|---|---|
| Session context is lost | Board, tasks, decisions and a Hand-off note per task live in planning/; a new session reads them and continues |
| Changes need scope approval | No code before you approve the task's scope; commits, pushes and deployments each need their own approval |
| Work needs separate verification | QA is a separate role that runs the tests and checks every criterion; the Reviewer can only read |
Claude Code and Codex use the same files, so you can switch clients between steps.
You need Node.js 22+ and Claude Code. Nothing else is installed.
git clone https://github.com/ferhatcore/claude-codex-project-os.git
cd claude-codex-project-os
node scripts/init.mjs --target ../my-project --name "My Project"
cd ../my-project
claude
Then type /project-os-start and describe what you want to build. A typical first session:
You: /project-os-start
PM: New project, no repositories or tasks yet. What should we build first?
You: A small notes CLI in Node: add, list and delete notes, with tests.
PM: Drafted T-001 with four acceptance criteria (AC-1 … AC-4). Approve scope and code?
You: Approved. Code and tests only, no Git actions.
PM: Recorded. project-os-developer is implementing T-001 …
Developer handed over: 9 tests pass. project-os-qa is verifying …
QA: AC-1 to AC-4 pass with evidence. T-001 is done (not committed).
Close the session whenever you like. Next time run claude and type /project-os-resume: the PM reads the board and Hand-off notes and tells you what is done and what comes next.
Want to look around first? Add --example to the install command to get Trailboard, a small reading-list project with one proposed task.
A new folder (the installer never touches existing ones) containing:
CLAUDE.md rules for the PM session
START.md first-session procedure
.project-os.json project settings: repositories, worker cap, model preferences
.claude/agents/ project-os-developer, project-os-qa, project-os-reviewer (read-only)
.claude/skills/ /project-os-start, /project-os-task, /project-os-qa, /project-os-resume
planning/board.md what is in progress
planning/tasks/ one file per task: criteria, approvals, QA report, Hand-off
planning/decisions.md every approval, with date and wording
Nothing is written to your global Claude or Codex settings, and permissions stay as you have them. Subagents are limited by their tool lists, but your normal permission prompts still apply.
node scripts/init.mjs --target ../my-project --runtime codex
node scripts/init.mjs --target ../my-project --runtime both
Codex gets AGENTS.md, four role definitions in .codex/agents and the same four skills ($project-os-start and others). With both, the two clients share one planning folder. Only one writer works in a repository at a time, whichever client it uses. See the Codex guide.
flowchart LR
H[You: scope and approval] --> PM[PM: task and plan]
PM --> D[Developer]
D --> Q[QA]
Q -->|findings| D
Q -->|all criteria pass| C[PM: completeness check]
C --> A[You: approve Git actions]
QA can send work back to the Developer twice. A third attempt needs a new plan and your approval. Risky changes also get a security review and the read-only Reviewer. "Done" means verified, not committed or deployed.
Install a new workspace, then tell the PM where your repositories are during /project-os-start. It adds them to .project-os.json and proposes repository rules for your review. Your repositories keep their current files. See the quickstart and the customization guide.
- Quickstart: first session step by step, and connecting existing repositories.
- Claude Code notes and Codex setup.
- Workflows, customization and troubleshooting.
- Workspace templates and repository rules.
- Test report: the full workflow run with real Claude Code and Codex sessions.
- Contributing, security and release records.
node scripts/check.mjs
node --test scripts/system.test.mjs scripts/smoke.test.mjs scripts/runtimes.test.mjs
node --test examples/trailboard/repos/catalog/catalog.test.mjs
They cover all runtime and profile choices, the installed agents and skills, shared task state, installation refusals and the example. GitHub Actions runs them on Windows and Linux with Node.js 22. They do not start a model.
MIT. Copyright (c) 2026 Ferhat Kosger. An independent project; not affiliated with Anthropic or OpenAI.