Project OS workflow
A scaffold for Claude Code and Codex: tasks in files, developer and QA roles, manual approval and shared state.
- 70 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The initializer writes only into a new folder, while role agents change code in the repositories you attach.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add workflows/project-osDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The initializer writes only into a new folder, while role agents change code in the repositories you attach.
This is third-party code. Review the repository files before installing.
What it does
Project OS creates a structure for agent work in a new folder: task files, decisions, repository rules and split roles. A PM records decisions, writes tasks and assigns work, a developer makes the change, QA checks the result against the task before a human approves it. Progress lives in files, so a new session continues without re-explaining. `node scripts/init.mjs --target <folder> --runtime claude|codex|both` prepares the workspace. Claude Code gets `CLAUDE.md`, Codex gets `AGENTS.md`, project skills and four roles: PM, Developer, QA and Reviewer. You can switch clients between steps because the planning directory is shared.
Who it is for. Solo developers and small teams running a project with Claude Code and Codex who lose context between sessions.
Good fit when
- The project runs over many sessions and each starts by retelling the previous one.
- An independent check of the result against the task is needed, not the author's self-review.
- You switch between Claude Code and Codex and want the plan in one place.
- Tasks span several repositories and need one list with a worker cap.
Not a fit when
- One short edit is enough and a role structure would be overkill.
- Integration with a tracker such as Jira is needed: planning runs on files only.
- The agent runs without Node.js: the initializer needs version 22 or newer.
Example request
Read START.md, take the first planning task, hand it to the developer and send it to QA after the edit.Limitations
Node.js 22 or newer is required. The installer creates a new folder and leaves existing repositories and global client settings alone, so attaching a live project is described in `QUICKSTART.md`. In Codex roles are chosen through built-in delegation, and if the client cannot assign a role the PM passes its instructions in the task text. The installer starts no agents and makes no model requests.
How to disable. Delete the created project folder or remove `CLAUDE.md`, `AGENTS.md` and the `.codex/` and `.agents/` directories from it. Delete the installer clone separately.
FAQ
Which client should I choose?
Pass `--runtime claude`, `--runtime codex` or `--runtime both`. With `both` the two clients work on the same planning files.
What is the Trailboard example?
A demo project with a reading list, a small CLI and a status filter task. The `--example` flag creates it to walk through a first session.
Who accepts the work?
A human. QA checks the result against the task criteria, then the approval decision stays with you.
How many agents run at once?
The cap is set in `.project-os.json`: `lean`, `standard` or `heavy`. It limits the number of workers.
Can I attach my own repository?
Yes. For your own project omit `--example` and set `--name`, and attaching existing repositories is covered in `QUICKSTART.md`.
Discussion
No questions or reviews yet.
Related
WorkflowsA skill that keeps project memory in plain Markdown files: session logs, a wiki, rules, a to-do list and a note on where to resume
A plugin for Claude Code and Codex: department folders with rules and 35 skills to run a one-person company through AI agents
A CLAUDE.md and AGENTS.md file with seven principles: the agent frames the problem and scope before it writes code
A workspace with AGENTS.md and 49 skills for product managers: backlog, goals, priorities, PRDs and verified execution
An Obsidian vault template for Claude Code: /daily, /weekly, /monthly and /project commands link three-year goals to today's tasks
cowork-os builds a Markdown workspace for Claude Cowork: team decisions, context, next actions and recurring routines.
README in short
Shows client choice, three initializer runs, the installed files, a task's path from PM to QA and the Trailboard example.