DevMode is a high-discipline, token-efficient, and multi-IDE agentic engineering framework. It extends the core rules of Jesse Vincent's Superpowers to enforce mode classification, strict token-budget rationing, clean git worktree boundary protection, and rigorous verification gates.

                  +-----------------------------------+
                  |           Agent Invoked           |
                  +-----------------------------------+
                                    |
                                    v
                  +-----------------------------------+
                  |     skills/using-devmode/         |  <--- Mandatory Bootstrap
                  +-----------------------------------+
                                    |
            +-----------------------+-----------------------+
            |                                               |
            v                                               v
+-----------------------+                       +-----------------------+
|  MODE: INVESTIGATION  |                       |  MODE: IMPLEMENTATION |
|  - token-budget       |                       |  - test-driven-dev    |
|  - workspace-isolation|                       |  - systematic-debug   |
|  - explore-first      |                       |  - verify-before-done |
+-----------------------+                       +-----------------------+
            |                                               |
            +-----------------------+-----------------------+
                                    v
                  +-----------------------------------+
                  |       skills/worker-handoff/      |  <--- Structured Handoff
                  +-----------------------------------+

• 🌿 The Core Philosophy
• 🛡️ The Four Iron Laws
• 📦 Available Skills (20 total)
• ⚙️ Installation & Harness Setup
• 🤝 Contributing & TDD-for-Skills
• ⚖️ Attribution & Licensing

AI agents are extremely powerful, but left to their own devices, they suffer from context expansion bloat, lazy verification loops, and symptom-oriented patching.

DevMode converts the agent's environment into a high-leverage discipline harness:

1. Discipline First: No code is written without a TDD failing test first. No bug is fixed without systematic root-cause investigation first.
2. Context Rationing: Broad file reads and generic directory searches are strictly gated by the token-budget skill. The agent must search first and read selectively.
3. Workspace Isolation: Agents operate in clean, isolated, git-protected worktrees or task branches, preventing state pollution.
4. Independent Seams: Code is decomposed into deep modules with small interfaces, maximizing testability and AI comprehension.

DevMode is governed by the canonical contract in docs/devmode-contract.md.

The short version:

1. Mode Gate — classify the task before acting.
2. Context Gate — search before broad reads.
3. Change Gate — isolate edits and choose the right workflow.
4. Verification Gate — provide fresh evidence before claiming completion.

Harness-specific files should route agents to the contract instead of duplicating the full rules.

DevMode includes a curated library of 20 specialized skills organized under the four operational gates:

• using-devmode: The master session bootstrap. Dictates mode gating and skill routing.
• brainstorming: Multi-approach visual exploration before design doc creation.
• writing-plans: Bite-sized, zero-placeholder implementation checklists.
• executing-plans: Plan execution inside the current session with review gating.

• token-budget: Strict token economics. Replaces lazy read loops with search-first patterns.
• token-optimization: Project-local lightweight context and search-policy management.
• grill-with-docs: Interactive spec refinement using CONTEXT.md and ADRs.

• test-driven-development: Strict RED-GREEN-REFACTOR loops. No code without tests.
• systematic-debugging: Investigate before fixing. Includes root-cause-tracing and defense-in-depth modules.
• workspace-isolation: Strict workspace boundaries. Prevents edits leaking to protected directories.
• using-git-worktrees: Seamlessly provisioning isolated git worktrees.
• subagent-driven-development: Isolated subagent execution with independent spec and quality reviewers.
• dispatching-parallel-agents: Orchestrating parallel non-dependent sub-tasks.
• improve-codebase-architecture: Surfacing shallow modules and generating visual deepening reviews.
• writing-skills: Applying TDD to process documentation (RED-GREEN-REFACTOR for skills).

• verification-before-completion: Concrete evidence checking before claiming completion.
• worker-handoff: Rigorous task handoff protocol using verified evidence.
• requesting-code-review: Preparing clean PR reviews.
• receiving-code-review: Implementing feedback with technical rigor.
• finishing-a-development-branch: Automated branch verification and merge readiness.

DevMode can be integrated with major AI coding harnesses (such as Claude Code, Gemini, Cursor, Codex, and OpenCode) via symlinks, prompts, or custom loader configurations. Follow the setup instructions for your specific environment below:

Claude Code automatically scans .claude-plugin/plugin.json to load custom skills.

1. Clone this repository into your project root:

   git clone https://github.com/870DudeMcgee/devmode.git .devmode

2. Symlink the .claude-plugin config:

   ln -s .devmode/.claude-plugin .claude-plugin

3. Symlink the skills folder:

   ln -s .devmode/skills skills

Gemini CLI uses a bootstrap config mapping.

1. Reference gemini-extension.json in your global config.
2. Gemini CLI will automatically load GEMINI.md as its starting prompt context, bootstrap-loading using-devmode.

Cursor respects directory instruction prompts.

1. Link Cursor's system prompt instructions to .devmode/skills/using-devmode/SKILL.md to trigger full framework awareness on every new chat session.

1. Copy or link .codex-plugin/ directory to your project root.
2. Codex will discover the UI metadata and register DevMode skills.

Follow instructions in .opencode/INSTALL.md to set up the bootstrap loader.

DevMode includes experimental VS Code / GitHub Copilot guidance:

• .github/copilot-instructions.md
• .github/instructions/devmode.instructions.md
• .github/prompts/devmode-plan.prompt.md
• .github/prompts/devmode-review.prompt.md
• docs/vscode-copilot.md

See docs/vscode-copilot.md for setup and usage.

We love contributions! However, to maintain the rigorous discipline of DevMode, all skill additions and modifications MUST follow the TDD-for-Skills process:

1. RED Phase: Write a pressure scenario (under the /tests folder) that triggers the failure you want to prevent. Run an agent without your changes and verify it fails.
2. GREEN Phase: Implement your skill in skills/your-skill/SKILL.md to address the specific excuse or loophole. Run the agent with the skill and verify it now complies.
3. REFACTOR Phase: Plug any remaining loopholes by updating the rationalization table in your skill.

For complete guidelines, read writing-skills and the Contributing Guide.

DevMode is released under the MIT License.

It is based heavily on Superpowers by Jesse Vincent and the team at Prime Radiant. We are deeply grateful for their trailblazing work on AI agent discipline. Comprehensive attribution details can be found in ATTRIBUTION.md.