Deep Work Plan

Product Introduction

1. Definition: Deep Work Plan is an open-source, MIT-licensed AI agent harness methodology and kit that transforms any code repository into a structured, self-documenting execution environment for long-running, autonomous AI coding tasks. It functions as a durable spec-driven framework embedded directly within the repository's Git structure, replacing transient chat interfaces with persistent operational blueprints.
2. Core Value Proposition: It solves the critical problem of AI agent context drift and task abandonment during complex, multi-hour coding sessions (e.g., major refactors, subsystem migrations). By making the repository itself the harness, Deep Work Plan ensures any AI agent (Claude Code, Cursor, Codex, etc.) executes with precision, maintains plan integrity across context resets, and delivers verifiable, resumable work without vendor lock-in.

Main Features

1. Reasoning-Based Repository Onboarding: This is not a templated scaffolder. The onboarding prompt (/init.md) initiates an autonomous process where the connected AI agent performs deep repository analysis. It inspects manifests (package.json, pyproject.toml), folder layouts, and CI/CD configurations to reason about the actual stack, archetypes (individual repo vs. orchestrator hub), and validation commands. This generates a context-aware AGENTS.md, categorized docs/ tree, and .agents/ kit with real commands, avoiding generic placeholders.
2. Spec-Driven, Resumable Execution Engine: The core of the methodology is the Deep Work Plan itself. Tasks are decomposed into atomic subtasks with explicit acceptance criteria and validation gates (like test suites or lint commands). The plan state is persisted in a gitignored .dwp/ folder within the repository. This enables git-native resumability; if an agent's context overflows or a session ends, any agent can read the plan and pick up exactly where the last one left off, ensuring long-horizon work continuity.
3. Agent-Agnostic, Markdown-Coupled Architecture: The entire framework is built on plain Markdown and Bash, making it universally compatible. The methodology installs a standardized Deep Work Plan skill pack (with sub-skills for create, execute, refine, resume, verify, etc.) into the repository. This skill pack is the single, reusable engine. Adapter instructions are then generated for specific agents like Claude Code (using AGENTS.md and slash commands), Cursor, or GitHub Copilot, ensuring one methodology works across all tools without altering the core harness.

Problems Solved

1. Pain Point: AI Agent Context Amnesia and Execution Drift in long-duration tasks. Standard AI coding agents lose coherence on tasks exceeding a single session, forgetting prior decisions, architectural constraints, and progress. Deep Work Plan mitigates this by shifting the source of truth from the agent's volatile context to the durable, version-controlled AGENTS.md and .dwp/ plan files within the repository.
2. Target Audience: Software engineering teams and individual developers leveraging AI coding agents for production-grade work. This includes full-stack developers, DevOps engineers, and platform architects working with stacks like Django, FastAPI, TypeScript/React/Next.js, Go, or Rust. It is especially critical for teams performing large-scale code migrations, refactors, or building complex subsystems that require reliable, multi-step automation.
3. Use Cases:
   • Autonomous Legacy Refactor: Defining a multi-step plan to upgrade a legacy monolith to a microservices architecture, with each service's migration as a verified subtask.
   • Cross-Repository Orchestrator: Coordinating a feature rollout across five interconnected repositories from a central "hub" plan.
   • CI/CD Pipeline Enhancement: Automatically generating and verifying documentation and agent instructions as part of a repository's initialization or continuous integration process.
   • Resumable Development Sprints: Allowing a developer to initiate a complex feature build with an agent, walk away, and have another agent (or the same one later) continue from the precise checkpoint after a context reset.

Unique Advantages

1. Differentiation vs. Traditional Methods: Unlike simple chat-based AI coding or one-off scaffolding tools, Deep Work Plan is a sustained methodology layer. It doesn't just generate code; it installs an ongoing operational framework. Compared to tool-specific solutions (e.g., GitHub Copilot's chat), it is vendor-agnostic and repository-centric, with state managed via Git rather than external databases or IDE state. The result is a portable, verifiable, and auditable system where "AI-first" is a checked state (/dwp-verify), not an assertion.
2. Key Innovation: The core innovation is harness engineering made portable and repository-embedded. By reasoning to adapt the harness (AGENTS.md, docs/, .agents/) to the specific repository and storing execution plans in .dwp/, Deep Work Plan decouples the durable plan from the transient agent session. This creates a resumable state model entirely within Git, allowing any compliant agent to act as a pilot for the repository, eliminating lock-in to a specific AI model or coding assistant.

Frequently Asked Questions (FAQ)

1. How does Deep Work Plan support different programming languages and frameworks like Python, TypeScript, or Go? Deep Work Plan uses a reasoning-first onboarding process rather than relying on static templates. During setup, the connected AI agent analyzes your repository's actual package manifests (package.json, requirements.txt, Cargo.toml), directory structure, and CI scripts to infer the correct stack, build commands, and test frameworks. It then generates tailored AGENTS.md instructions and validation gates based on these real commands, ensuring compatibility with any stack, from Django REST Framework to Rust Cargo projects.
2. Is Deep Work Plan a replacement for AI coding tools like Cursor, GitHub Copilot, or Claude Code? No, it is a complementary methodology and harness layer that works with these tools. Deep Work Plan provides the structured plan and repository context (AGENTS.md), while tools like Cursor or Claude Code serve as the execution agents that read and follow this plan. It standardizes the what (the plan) and where (the repository harness), allowing you to use the best how (the specific AI agent) for the task.
3. How does the system ensure an AI agent doesn't drift from the original plan during a long execution? The plan itself is the source of truth, enforced through validation gates. Each subtask in a Deep Work Plan includes explicit acceptance criteria and predefined validation commands (e.g., npm test, pytest, cargo check). The executing agent must run these gates and achieve a pass result before proceeding. The plan state in .dwp/ is updated atomically with the agent's progress, and the AGENTS.md rules provide persistent guardrails that the agent must reference, creating a closed-loop, self-verifying execution cycle.
4. What does "Open Source, MIT" mean for my use of Deep Work Plan? It means you can freely use, modify, and distribute the Deep Work Plan methodology, specification, and kit under the permissive MIT license. There is zero telemetry—no data is sent back from the installed harness. All outputs (plans, drafts, generated docs) reside in a local, gitignored .dwp/ folder or are committed to your own repository, giving you full control and auditability over the system and your code.