The Process

A structured workflow for human + AI agent teams. Two AI agents coordinate through GitHub issues — one implements, one reviews — with a human lead making all final decisions. Works across Claude Code, Codex CLI, and Cursor.

The Idea

AI agents are powerful but undisciplined. They drift from plans, skip reviews, merge without thinking. The-process adds structure: every task flows through plan → review → implement → review → merge → learn. A GitHub issue is the shared conversation log. Agents only post during explicit handoffs. Everything else happens locally.

The result: traceable decisions, structured reviews, and a human who stays in control without micromanaging.

Two Modes

Full process — two agents in separate terminals, coordinating through an issue. One implements, one reviews. For complex, multi-package work where you need the rigor.

Solo mode — one agent, one terminal, one issue comment at the end. For clear-scope tasks where the full ceremony is overkill.

How It Works

Human creates issue → /pickup implementer 42
                         ↓
                    Plan → /pause 42 → plan posted to issue
                         ↓
                    /pickup reviewer 42
                         ↓
                    Review plan → feedback posted
                         ↓
                    Lead: "Plan approved"
                         ↓
                    Implement → /pause → /deep-review
                         ↓
                    Iterate until clean → Lead merges
                         ↓
                    /retro 42 → learnings posted by both agents

Solo shortcut: plan → implement → /deep-review (self) → merge → /wrap-up

Core Skills

Skill	What it does
/pickup	Resume work on an issue — reads the thread, determines phase, orients
/pause	Hand off to the other agent via structured issue comment
/deep-review	Single-agent structural review with technique triage
/research-threads	Hypothesis-driven investigation when you're stuck
/retro	Post-merge retrospective with evidence-backed learnings
/wrap-up	Solo mode: post consolidated summary to issue

Extended Skills (via overrides)

Available in overrides/skills/ as personal Layer 2 skills. Not committed — add your own or copy from examples. See Customization.

Skill	What it does
/plan	Council-informed planning: 3 agents debate the approach
/review	5-agent deep code review: structural, behavioral, failure modes, sanity, completeness
/review-plan	Staff-engineer plan review: correctness, scope, risks
/council	Engine behind /plan and /review — spawns parallel agents, synthesizes
/docs	Generate ephemeral project docs to /tmp/claude-docs/
/onboarding	Interactive tutorial — the agent teaches you the-process

Architecture: 3 Layers

Layer 0    Bare CLI defaults (nothing installed)
Layer 1    the-process (committed, shared with team)
Layer 2    overrides/ (gitignored, per-machine personal config)

Layer 1 is everything in this repo: skills, workflow doc, agent instructions. Shared, committed, upstream-compatible.

Layer 2 is overrides/ — gitignored, lives only on your machine. Add personal skills, hooks, or agent behavior. Layer 2 wins over layer 1 on collision.

Incognito: tp --off removes all symlinks. You're back to bare defaults. tp --on re-installs.

What lives where

the-process/
├── the-process.md          # Workflow doc (layer 1)
├── INTERNALS.md            # Agent-facing architecture docs
├── skills/                 # Layer 1 skills (committed)
│   ├── deep-review/
│   ├── pause/
│   ├── pickup/
│   ├── research-threads/
│   ├── retro/
│   ├── review-plan/
│   └── wrap-up/
├── overrides/              # Layer 2 (gitignored)
│   ├── skills/             # Personal/override skills
│   ├── hooks/              # Personal hooks
│   └── AGENTS.md           # Replaces base if present
├── install.sh              # Multi-CLI installer
├── setup.sh                # Re-sync from manifest
├── common_functions.sh     # Shared shell primitives
├── tp.sh                   # Shell wrapper (sourced by rc)
└── lint.py                 # Structural linter

Install

One-line (remote)

curl -fsSL https://raw.githubusercontent.com/Shubhaankar-Sharma/the-process/main/install.sh | bash

From clone

git clone https://github.com/Shubhaankar-Sharma/the-process.git
cd the-process
./install.sh

The installer:

1. Detects which AI CLIs you have (Claude, Codex, Cursor)
2. Symlinks skills and workflow docs to each platform's global config
3. Copies AGENTS.md (personal overrides replace the base if present)
4. Optionally installs the tp() shell wrapper

Re-sync (after install)

./setup.sh             # Install layers 1+2
./setup.sh --off       # Incognito mode
./setup.sh --status    # Show what's installed

The tp wrapper

Added to your shell rc by the installer. Manages layers, skills, and sync.

tp --on                # Re-sync installed layers
tp --off               # Incognito: strip all layers
tp --status            # Show what's installed
tp skills              # Interactive skill toggle
tp disable <name>      # Disable a skill
tp enable <name>       # Re-enable a skill
tp add <url>           # Install skill from URL
tp sync                # Git pull + re-install

Multi-CLI support

All three CLIs consume the same skill format. Skills are symlinked from one source.

CLI	Skills	Agent instructions	Workflow
Claude Code	~/.claude/skills/	~/.claude/AGENTS.md	~/.claude/workflows/
Codex CLI	~/.agents/skills/	~/.codex/AGENTS.md	—
Cursor	~/.cursor/skills/	~/.cursor/rules/the-process.md	—

Customization

Add a shared skill: create skills/<name>/SKILL.md, re-run setup, commit.

Add a personal skill: create overrides/skills/<name>/SKILL.md, re-run setup. Gitignored.

Override a skill: copy it to overrides/skills/<name>/SKILL.md and edit. Wins on collision.

Change agent behavior: edit AGENTS.md (shared) or overrides/AGENTS.md (personal).

New to the-process? Install the onboarding override and run /onboarding — the agent walks you through everything interactively.

For full internal docs on how the setup works, see INTERNALS.md.

Credits

Forked from systay/the-process. Original workflow and core skills by the PlanetScale team.

License

MIT