A workspace template for working with AI coding assistants (Claude Code, Codex, Cursor, Gemini) across multiple projects — both brand-new projects and existing repositories. Designed to feel like working with a senior dev mentor who knows when to just execute and when to teach.
AgentJoJoy is a governance layer, not an agent runtime.
It gives humans and AI agents a safe operating manual, memory, and handoff system for your local projects.
Use it to:
- Resume work without losing context.
- Let Claude, Codex, Cursor, and Gemini share one workspace safely.
- Upgrade AI operating rules without overwriting project memory.
AgentJoJoy is the context and governance layer between the language model and the execution runtime. It does not reason — that is the model — and it does not execute — that is the runtime (Claude Code, Codex, Antigravity, and others). It supplies the rules, project context, and safety boundaries that constrain how any model and any runtime work together.
In practice it provides portable, human-readable contracts: workflow rules and safety gates, onboarding/intake context, SmartWorkers, Loop Contracts for governed autonomous runs, Hook Enforcement Contracts, and optional local/alternative-provider fields.
AgentJoJoy does not run agents, install daemons, replace Claude Code / Codex / Antigravity, or force a multi-agent workflow. It stays vendor-neutral and team-safe by design — every layer is opt-in and contract-first.
- Click Use this template on GitHub to create your own AgentJoJoy workspace repository.
- Clone your new repository to your machine.
- Open Claude Code, Codex, Cursor, or Gemini at the workspace root.
- Ask the AI to read
CLAUDE.md/AGENTS.mdand start onboarding. - Choose New Project or Existing Project when the AI asks.
Already have an AgentJoJoy workspace? Use the Upgrading flow instead of creating a fresh template copy, so your project notes, decisions, and custom skills are preserved.
- Private-by-default workspace wrapper — keeps assistant context beside your project instead of inside it, so personal AI notes stay out of project commits.
- Auto-loading agent rules —
CLAUDE.mdandAGENTS.mdgive Claude Code, Codex, Cursor, and Gemini a shared starting point. - Context-aware rule loading — agents load the smallest matching context bundle for resume, debug, review, onboarding, git/worktree, and skill work instead of re-reading every rule file every turn.
- 4 Pillars of Workspace Governance — structures AI permissions, budgets, scope limits, and execution safety into a logical 4-pillar model.
- 3 Onboarding Gateways — channels the onboarding process into New Project, Existing Project, or Resume flows under strict security guardrails.
- Consolidated Workspace & Operations Model — merges structural rules, Directory Junction rules, and local git-sync decisions into one cohesive guide.
- 5-Step Skill Precedence Hierarchy & Sandboxing — establishes strict sandboxing boundaries and priority guidelines to govern portable skills execution safely.
- Guided onboarding — choose a new project or wrap an existing repo; the AI fills only the context you approve.
- Dual engagement modes — switch between
executefor terse delivery andteachfor pair-programming explanations. - Milestone teaching & opt-in auto-commit — on complex work the AI breaks the task into verifiable milestones and (in
teachmode; toggleable inengagement-mode.md) shows a short "why it works / where it can break" teaching box in chat at each one, and can optionally make clean local checkpoint commits (off by default; pushing always asks). - Masked secret intake — secrets are entered locally through a masked prompt and referenced by env-var name; the AI never asks for or prints a secret value in chat.
- Generic input handling — for tools that process variable input, the AI handles the whole input class (encodings, formats, edge cases) by naming its dimensions of variation, instead of patching one failing case at a time.
- Wrapper isolation by default — onboarding keeps your AI context out of the project repo (gitignores
AgentJoJoy/), so personal notes never land in project history. - Multi-agent coexistence — coordinate Claude Code, Codex, Cursor, and Gemini without branch or attribution confusion.
- Cursor bridge fallback discipline — Cursor wrapper walk-up is the default; repo-local bridge files are fallback-only after a real discovery failure and stay local-only in team repos unless explicitly approved.
- Technical Precedents Logging — AI proactively logs resolved technical blockers and workarounds to a transparent markdown file.
- Read-only resume checks — refreshes local branch/worktree state without fetch, pull, push, rebase, merge, or branch switching.
- Junction Link Model — supports rigid runtime folders with Windows Directory Junctions while keeping AI system files isolated.
- Test-first discipline — encourages the AI to write or stub the failing/reproducing test before implementation or debugging.
- AI-NO-OVERWRITE Protection — protects custom configurations and codebase sections from being changed by the AI or lost during upgrades.
- Portable skills —
SKILL.mdroutines for debugging, review, root-cause analysis, stakeholder updates, and design interviews. - SmartWorker framework — when recurring work needs knowledge (not just a script), the single Main Agent dispatches a worker into a separate context and gets back a synthesized result, keeping its own context clean; a runtime-neutral spec maps to each agent's native subagent mechanism. Not multi-agent orchestration.
- Loop Contracts (governed autonomous runs) — run a SmartWorker unattended under an owner-approved contract: machine-checkable definition of done, work tiers (deliver-an-artifact / deliver-to-a-gate / never-autonomous), strict write scope, budget and pacing caps, and escalation rules. The owner approves the envelope once; no human sits in the loop. Activation requires mechanically enforced gates proven by a live blocking pre-flight — AgentJoJoy ships no scheduler; your runtime's native cron/scheduled-tasks executes, the contract governs.
- Hook Enforcement Contracts — optional docs/templates for owners who want to mechanize selected AgentJoJoy or project-specific gates in Claude Code, Codex, Antigravity, or Hermes; no hook scripts/configs are active by default.
Each project gets its own wrapper folder containing:
- The actual project content (a git repo, docs, anything)
- A
AgentJoJoy/sibling holding personal AI context - A central
CLAUDE.md/AGENTS.mdat the root that drives the AI
| Context | Tool | Entry Point | Onboarding Path |
|---|---|---|---|
| Team repo (work) | Claude Code + Cursor | CLAUDE.md + AGENTS.md |
Path 2 + English default |
| Personal project | Claude / Codex / Gemini | CLAUDE.md / AGENTS.md |
Path 1 + preferred language |
The template automatically detects whether the workspace is new, partly configured, or ready to resume:
graph TD
A[Start Session in Workspace] --> B{Classify State}
B -->|New workspace| D{Choose Onboarding Path}
B -->|Partly configured| E[Resume Intake Flow]
B -->|Ready to resume| F[Resume Check Protocol]
D -->|Path 1: New Project| G[Scaffold & Auto-fill templates]
D -->|Path 2: Existing Project| H[Read-only scan & Pre-fill templates]
D -->|Skip| I[Bypass Onboarding for Session]
F --> J[Check Git Status & agent-records/progress-tracker.md]
J --> K[Ask to continue active task or start new task]
- Path 1 — New project: AI asks minimal questions, proposes a folder structure, and scaffolds empty templates.
- Path 2 — Existing project: AI scans the project read-only (README, manifests, git status), extracts context, fills metadata, and proposes a portable rules snippet for the target repo.
When a session starts in a configured workspace, the AI reads AgentJoJoy/agent-records/progress-tracker.md, checks git status, reports active worktrees/branches, and asks whether to resume the current task or start a new one.
AgentJoJoy routes each task to a small context bundle instead of asking the AI to re-read every rule file on every turn. Resume, debug, review, onboarding, git/worktree, and skill tasks each have a focused reading path; mutable state such as git status, the active tracker, and current diffs is refreshed only when relevant.
The workspace-root README.md is bootstrap scaffolding, and the root
CHANGELOG.md / LICENSE are AgentJoJoy's own files — they describe the
template, not your project. Once onboarding finishes, hand the workspace
root over to the project: the project README lives inside the real project
folder, and the template's changelog and license move under AgentJoJoy/:
<workspace-root>/
├─ AgentJoJoy/
│ ├─ CHANGELOG.md ← template changelog (moved from root)
│ └─ LICENSE ← template license (moved from root)
├─ CLAUDE.md
├─ AGENTS.md
└─ <project-folder>/
└─ README.md
For existing projects, keep the project's own README if it already exists. If
it does not, create <project-folder>/README.md from project facts instead of
moving AgentJoJoy product text into it. After that, remove or explicitly defer
cleanup of the root bootstrap README. Your project's own changelog and
license, if any, then own the root namespace.
This keeps daily git work focused on the real project folder. Existing projects usually already have their own remote and README; AgentJoJoy remains a local operating layer beside that project instead of competing with the project's public documentation.
AgentJoJoy is designed so that everything stays on your machine unless you choose to share it. We aim for transparency over implicit behavior — the AI should never quietly collect, transmit, or do anything to your data that you didn't explicitly agree to.
- Project templates (
AgentJoJoy/agent-context/*.md) — filled during intake from your answers and any read-only repo scans. You see and approve every fill. AgentJoJoy/agent-records/progress-tracker.md— daily work tracker. The AI updates it after meaningful work actions.
The Technical Precedents file (AgentJoJoy/agent-context/technical-precedents.md) is a flat markdown file under agent-context/ that serves as the workspace's memory of validated technical solutions and workarounds.
- The AI will proactively log issues and solutions here whenever it resolves a technical blocker or debugs an environment-specific workaround.
- Future AI sessions read this file when debugging, troubleshooting tooling, or following a tracker link to a relevant precedent, preventing the AI from repeating past technical mistakes or re-asking solved questions.
- It is fully transparent, editable, and local to your workspace wrapper.
- ❌ No telemetry, no analytics, no usage tracking sent off-machine.
- ❌ No automatic uploads, fetches, or remote calls from any helper script.
- ❌ No background daemons or scheduled tasks installed.
- ❌ No writes to your project repo's git history (precedents live outside the wrapped repo).
- ❌ No remote uploads or sync — precedents remain local to the workspace.
When the upstream base branch (main) moves while you have work in progress, AgentJoJoy helps you choose the best sync strategy:
- Merge — preserves history. Recommended when task commits are already pushed or under PR review.
- Rebase — replays commits onto the latest
main. Recommended when task commits are local-only and clean. - Squash & Rebase — collapses noisy WIP commits into one before replaying. Recommended for messy/WIP local work.
See AgentJoJoy/agent-rules/workspace-model.md for the full decision guide.
AgentJoJoy/agent-records/progress-tracker.md— hot index of active branches, worktrees, tasks in progress, and next steps. Read first by the AI.AgentJoJoy/agent-records/setup-tracker.md— temporary hot setup/onboarding tracker.AgentJoJoy/agent-records/setup-history/— cold archive for completed setup/onboarding history.AgentJoJoy/agent-records/decisions/— key decisions log for the wrapped workspace.AgentJoJoy/agent-records/work/— optional archive records for selected completed or paused work, loaded on demand.
AgentJoJoy/agent-context/project-overview.md— project identity, type, stack, work areas.AgentJoJoy/agent-context/architecture.md— codebase architecture, invariants, boundaries (optional).AgentJoJoy/agent-context/standards.md— code style and testing guidelines.AgentJoJoy/agent-context/ui-context.md— UI framework context (optional).AgentJoJoy/agent-context/domain-language.md— project-specific glossary (optional).AgentJoJoy/agent-context/technical-precedents.md— triggered technical memory for debug, tooling, environment, and known-workaround tasks.
CLAUDE.md/AGENTS.md— entry points that load automatically and define session start protocols.AgentJoJoy/agent-rules/workflow-spec.md— canonical SPEC-1 to SPEC-9 rules (Strategic choices, approvals).AgentJoJoy/agent-rules/ai-workflow-rules.md— AI permission boundaries structured as 4 Pillars of Workspace Governance (safety gates, command/git execution boundaries).AgentJoJoy/agent-rules/intake-flow.md— onboarding framework organized into 3 Onboarding Gateways (Path 1, Path 2, and T2 Resume) with strict "Security-First Guardrails Always".AgentJoJoy/agent-rules/workspace-model.md— Consolidated Workspace & Operations Model merging layout specifications, operating commands, and git-sync policies (Merge, Rebase, Squash & Rebase) into a single unified reference.AgentJoJoy/workflow-guide.md— English onboarding manual.AgentJoJoy/workflow-guide-th.md— Thai onboarding manual.AgentJoJoy/agent-smartworkers/— SmartWorker framework: runtime-neutral spec + template for Main-dispatched knowledge workers, plus the Loop Contract template for governed autonomous runs (not multi-agent orchestration).AgentJoJoy/agent-hooks/— optional Hook Enforcement Contracts: docs/templates only with per-runtime binding notes; owners choose whether, where, and how to implement any hook.AgentJoJoy/agent-templates/— optional snippet library and portable inserts, loaded only when needed.AgentJoJoy/agent-records/decisions/— key decisions log.
AgentJoJoy/skills/README.md— portable skill layers configuration with a 5-step Priority of Precedence safety matrix, strict sandboxing boundaries, and active/passive skill discovery heuristics.AgentJoJoy/skills/agentjojoy-core-practices/SKILL.md— portable routines for Debugging, Code Review, Root Cause Analysis, and Management-Talk rewriting.AgentJoJoy/skills/grill-me/SKILL.md— structured design interview for vague plans.
Note: AgentJoJoy skills don't appear in the
/command palette. They're discovered by the AI reading the workspace and matching the skill description against your request — just describe what you want and the AI will pick the right skill fromAgentJoJoy/skills/. Adding a skill is drag-and-drop: place a folder containing aSKILL.mdintoAgentJoJoy/skills/and the AI sees it viagit statuson the next interaction — no install or restart needed.
For a new workspace, use GitHub's template flow:
- Click Use this template on the GitHub repository page.
- Create a new repository under your account or organization.
- Clone that new repository to your machine.
- Open your AI assistant at the cloned workspace root.
- Paste:
Please read CLAUDE.md / AGENTS.md and start the AgentJoJoy onboarding intake flow.
The AI will load the workspace rules and ask whether this is a new project, an existing project, or something to skip for now.
If you already have a project repo or document folder, create an AgentJoJoy workspace first, then choose Existing Project during onboarding. The AI will scan the existing project read-only, explain where personal AI files live, and ask before moving, cloning, linking, or writing anything.
If GitHub's template button is unavailable, clone or download this repository, copy the wrapper folder to your workspace, and remove the copied .git directory before onboarding. Prefer Use this template when available; it avoids the manual copy-and-cleanup step.
Note
Cross-platform note: The AgentJoJoy workflow and documents can be used on Windows, macOS, or Linux. AgentJoJoy does not ship active helper scripts by default; ask your AI assistant to adapt any one-off commands to the local shell, and approve any state-changing command first.
To return a workspace to its normal, unwrapped state (for example before sharing it or removing the personal AI operating layer), ask the current Main Agent to unwrap AgentJoJoy instead of running a bundled delete script.
Please help me unwrap AgentJoJoy from this workspace. First inventory the
AgentJoJoy files and records, ask what I want to preserve, show a dry-run
cleanup plan, and wait for my explicit approval before deleting anything.
Note
Preserve-first cleanup: The Main Agent should identify AgentJoJoy/agent-records/, decisions, work records, technical precedents, custom skills, and editor settings before proposing deletion of AgentJoJoy/, CLAUDE.md, AGENTS.md, VERSION, or legacy root tracker files. Any destructive filesystem command still requires explicit owner approval.
The Use this template button is only for creating a new workspace. To update an existing AgentJoJoy workspace, use the upgrade prompt below. The AI compares your workspace with a specific release tag, preserves your project-owned files, and asks before applying template changes.
AgentJoJoy is AI-driven, so upgrades are too. There is no install script to maintain and no package manager. Instead, you paste a canonical upgrade prompt into your AI assistant (Claude Code, Cursor, Codex, Gemini), and the AI handles the work using the project's own file-ownership rules.
Warning
Upgrading Pre-v1.2.4 Workspaces with Custom Skills: In template versions prior to v1.2.4, the file ownership rules (AgentJoJoy/agent-rules/file-ownership.md) classified the entire AgentJoJoy/skills/ directory as template-owned. If your workspace contains custom project-specific skills (i.e. folders in AgentJoJoy/skills/ other than agentjojoy-core-practices or grill-me), the upgrade agent may attempt to delete them. Before running the upgrade prompt, either manually edit your local file-ownership.md to classify your custom skills as user-owned, or explicitly instruct the agent: "Preserve my custom skills in AgentJoJoy/skills/ (do not delete or overwrite them)".
Tip
Protecting Custom Content with AI-NO-OVERWRITE: You can protect any custom settings, code, or notes in any file (even inside template-owned files) by wrapping them in HTML comment tags: <!-- AGENTJOJOY:AI-NO-OVERWRITE BEGIN --> and <!-- AGENTJOJOY:AI-NO-OVERWRITE END -->. The AI is strictly forbidden from altering or deleting anything inside these tags, and template upgrades will bypass them entirely.
type VERSION(The VERSION file lives at your workspace root and was stamped when you installed the template. If it's missing, your workspace pre-dates v1.2.0 — the upgrade prompt below handles that case.)
See CHANGELOG.md in this repository — and the Releases page for human-readable highlights per version.
Open your AI assistant in the workspace root and paste:
Please upgrade this AgentJoJoy workspace to the latest published template version.
Procedure:
1. Read the VERSION file at the workspace root. If it does not exist, treat the current version as "pre-v1.2.0" and proceed.
2. Identify the target version and fetch the latest source content. Try these in order:
a. Check the latest release tag from https://github.com/Joyperm/AgentJoJoy/releases and the public CHANGELOG.md.
b. Clone the target tag locally to a temporary folder using a shallow clone:
`git clone --depth 1 --branch <tag> https://github.com/Joyperm/AgentJoJoy.git temp-agentjojoy-upgrade`
(Use this clone as the source of truth for the upgrade.)
c. If fetching or cloning is unavailable (no network, blocked runtime, offline session), ask me for the target version and a local path to a pre-existing clone of that tag.
d. If neither is possible, stop and report what's missing — do not guess content.
3. If the local version equals the target version, stop and report "already at latest".
4. Otherwise, read AgentJoJoy/agent-rules/file-ownership.md to know which files are template-owned, user-owned, or mixed.
5. Walk the changes file by file (comparing the workspace files to the target clone source):
- For template-owned files: propose the new content; apply only after my approval.
- For mixed files: show a diff focused on structural/prose changes, preserve my filled values, apply after my approval.
- For user-owned files: do not modify. If a structural migration is required, propose a manual edit plan with per-section approval.
6. When done, update the VERSION file to the latest tag and log the upgrade in AgentJoJoy/agent-records/progress-tracker.md under Recent Actions with the date and version transition (e.g. "Upgraded AgentJoJoy template v1.1.0 -> v1.2.0").
7. Clean up by deleting the temporary upgrade directory (e.g. `temp-agentjojoy-upgrade`) using a safe OS command (e.g. `rmdir /s /q` or `Remove-Item`).
Constraints:
- Never run git push, pull, commit, merge, or branch switch without explicit approval.
- Check if a remote origin is configured for the workspace root repository before attempting any Git push operations. If no remote is configured, do not attempt to push and stop after committing locally.
- Preserve all content in agent-context/ and agent-records/.
- If unsure about a file's ownership, ask before changing it.
The AI will read AgentJoJoy/agent-rules/file-ownership.md, follow per-file approval gates, and never touch your project content. You can stop the upgrade at any point.
If you prefer a fully manual approach, the same file-ownership table in AgentJoJoy/agent-rules/file-ownership.md tells you which files are safe to overwrite from a freshly cloned latest version, which to leave alone, and which to merge by hand.
MIT License © 2026 Joyperm