A project-agnostic task and idea management plugin for Claude Code

CodeClaw gives your AI-assisted development workflow a structured backbone: ideas are captured, evaluated, promoted to tasks, implemented with quality gates, and tracked to completion — all through plain-text files and Claude Code slash commands. A gated release pipeline enforces strict development rules from branch creation to production tagging.

📖 Full Documentation — Architecture, API reference, configuration, deployment, troubleshooting, and more.

• 🔄 Two-pipeline workflow — separate idea evaluation from task execution
• 🛠️ 9 streamlined skills — unified slash commands (/task, /idea, /release, /docs, /setup, /update, /tests, /help, /crazy)
• 🚦 Gated release pipeline — 9 sequential stages with user-confirmed gates, feedback loops, and mandatory local build verification before every push
• 🏷️ Explicit version bump gate — all manifest files are discovered, verified, and updated with user confirmation before tagging
• 🌿 Three-branch strategy — enforced develop → staging → main promotion path with mandatory staging validation
• 🐳 Docker tagging — staging builds the latest tag, production builds stable + versioned tags
• 🧩 Claude Code plugin — install via marketplace, uninstall cleanly, update easily
• 📝 Plain-text tracking — tasks and ideas live in simple .txt files, fully version-controllable
• 🔗 GitHub/GitLab Issues integration — optional tri-modal sync with GitHub or GitLab Issues
• ✅ Quality gates — verification, linting, and smoke tests run before tasks can be closed
• 💻 Cross-platform — works on Linux, macOS, and Windows with automatic OS detection
• 🌐 Project-agnostic — works with any language, framework, or tech stack
• 👤 Human-in-the-loop — AI assists, but you make every decision at every gate
• ⚡ Yolo mode — append yolo to any command to auto-confirm all gates for fully autonomous execution

• 🧹 Release cleanup — 4.0.4 documentation and changelog corrections are now carried through the release line
• 🌿 Branch alignment — develop, staging, and main now share the same release history and tree
• 📝 Docs simplification — public docs and API reference no longer advertise retired legacy doc flows
• 🤖 [BETA] /crazy skill — fully autonomous end-to-end project builder
• 🎨 Frontend design wizard — template search, theme selection, color palette picker
• 🐾 Rebranded — CTDF → CodeClaw with plugin id claw

• Claude Code CLI installed and configured
• 🐍 Python 3.12+ (used by the bundled scripts)

/plugin marketplace add https://github.com/dnviti/codeclaw
/plugin install claw@dnviti-plugins

git clone https://github.com/dnviti/codeclaw.git
claude --plugin-dir ./codeclaw

1. Install the plugin using one of the methods above.

2. Set up task tracking in your project:

   /setup My Project Name
   

   This creates the task/idea files (to-do.txt, progressing.txt, done.txt, ideas.txt, idea-disapproved.txt), configures the three-branch strategy, and writes project guidance to project-context.md while creating AGENTS.md.

3. Start using skills:

   /idea create Add user authentication with JWT
   /idea approve IDEA-AUTH-0001
   /task pick
   /task status
   

4. When ready to release:

   /release continue 1.0.0
   

CodeClaw enforces strict development rules through two connected pipelines and a gated release process.

Ideas are lightweight proposals — what and why only. They must be explicitly approved before entering the task pipeline.

flowchart LR
    A[ideas.txt] -->|/idea approve| B[to-do.txt<br>becomes a task]
    A -->|/idea disapprove| C[idea-disapproved.txt<br>archived]

Tasks are actionable work items with technical details, file lists, and dependencies. Each task gets a dedicated branch for isolated development.

flowchart LR
    A["to-do.txt [ ]"] -->|"/task pick"| B["progressing.txt [~]"]
    B -->|"verify + close"| C["done.txt [x]"]

The release pipeline enforces a strict sequential process with built-in feedback loops. Every stage is gated — the release advances only when the stage passes ("OK"). Issues found at any stage create patch tasks (RPAT) that loop back to Stage 2.

flowchart TD
    S1["1. CREATE BRANCH<br>release/X.X.X from develop"]
    S2["2. TASK READINESS GATE<br>Verify all tasks complete<br>(blocks if tasks pending)"]
    S3["3. FETCH OPEN PRs<br>List PRs on release branch"]
    S4["4. PER-PR REVIEW<br>Sequential review and fixes<br>analyze → optimize → security →<br>comment → fix → merge → cleanup"]
    S5["5. MERGE TO STAGING<br>develop → staging<br>Local build gate → push<br>Builds 'latest' Docker tag"]
    S6["6. INTEGRATION TESTS<br>Full test suite on staging"]
    S7["7. MERGE TO MAIN + TAG<br>staging → main | Version bump gate |<br>Local build gate | Tag: vX.X.X |<br>CI check (platform-only) |<br>Builds 'stable' + 'vX.X.X' Docker tags"]
    S8["8. USERS TESTING<br>Release is live"]
    S9["9. END<br>Cleanup, final report"]

    S1 -->|OK| S2
    S2 -->|OK| S3
    S3 --> S4
    S4 -->|ALL PRs DONE| S5
    S5 -->|OK| S6
    S6 -->|OK| S7
    S7 --> S8
    S8 --> S9

    S4 -. "unresolved issues<br>create RPAT" .-> S2
    S5 -. "merge/build issues<br>create RPAT" .-> S2
    S6 -. "test failures<br>create RPAT" .-> S2
    S7 -. "CI failure<br>fix → tag move" .-> S7

Stage 7 contains multiple sub-gates including version bumping, local build verification, and conditional CI checks with a tag-move recovery loop.

flowchart TD
    M["7a. Merge staging → main<br>(Merge Template)"]
    CL["7b-c. Generate + update changelog"]
    VB["7d. VERSION BUMP GATE<br>Discover manifests → diff table →<br>user confirmation"]
    CT["7e. Commit + tag"]
    LB["7e-bis. LOCAL BUILD GATE<br>verify_command before push"]
    P["7f. Push production + tags"]
    CI{"7f-bis. Platform<br>enabled?"}
    SKIP["Skip to 7g"]
    DISC{"CI workflows<br>found?"}
    MON["7f-ter. Inspect triggered workflows"]
    RES["7f-quater. Collect results"]
    FIX{"Any fix<br>applied?"}
    TM["7f-quinquies. TAG MOVE<br>delete tag → pull fix →<br>local build gate → re-tag →<br>delete + recreate release"]
    REL["7g. Create platform release"]

    M --> CL --> VB --> CT --> LB --> P --> CI
    CI -->|"no / not enabled"| SKIP --> REL
    CI -->|yes| DISC
    DISC -->|"no workflows"| REL
    DISC -->|"workflows found"| MON --> RES --> FIX
    FIX -->|no| REL
    FIX -->|"yes (loop)"| TM --> CI

1. 🚦 Stages are sequential and gated — never skip a stage without explicit user override at a GATE.
2. 🚫 The release pipeline never implements tasks — Stage 2 is a readiness gate that blocks if any tasks are pending. Users must implement tasks via /task pick (or /task pick all) before the release can proceed.
3. 🧾 Open PRs are reviewed sequentially — each follows the full analyze → optimize → security → comment → fix → merge → cleanup sequence.
4. 🔧 Findings are fixed where possible, escalated where needed — unresolved issues become RPAT tasks and loop back.
5. 📝 Every PR comment is structured — findings and fixes are posted as separate, labeled comments for audit trail.
6. 🔒 Staging = Main minus public visibility — if it wouldn't survive on main, it doesn't pass staging.
7. 🏷️ Tags are only created on the production branch — after full pipeline through staging.
8. 🔄 Loop counter enforced — warnings at 3 iterations, forced choice at 5. Prevents infinite loops.
9. ✅ Local build and tests must pass before any push — catches regressions from version bump commits or post-merge changes.
10. 🏷️ Tags are moved, never recreated — when post-tag CI fixes are needed: delete tag → pull fix → rebuild → re-tag → delete and recreate platform release.
11. 📦 Version fields in all manifests must be bumped before tagging — explicit gate with user confirmation at Step 7d.
12. 📡 Remote CI checks are platform-only — without a connected platform, local build success is the sole pre-release gate.

flowchart LR
    DEV["develop<br><i>Active development<br>feature merges, task branches</i>"]
    STG["staging<br><i>Pre-release validation<br>'latest' Docker image</i>"]
    MAIN["main<br><i>Production: tagged releases<br>'stable' + 'vX.X.X' Docker images</i>"]

    DEV -->|merge| STG -->|merge + tag| MAIN

0.  /setup "My Project"                     → 📁 Create tracking files + branches
1.  /idea create "Add email notifications"  → 💡 Idea added to ideas.txt
2.  /idea approve IDEA-NOTIF-0001           → ✅ Idea promoted to task in to-do.txt
3.  /release create 1.0.0                   → 🏷️ Create release milestone
4.  /task schedule NOTIF-0001 to 1.0.0      → 📌 Assign task to release
5.  /task pick                              → 🌿 Branch created, briefing presented
6.  (implement the task)                    → 💻 Write code on task branch
7.  /task pick                              → ✅ Verify, close task, create PR
8.  /release continue 1.0.0                 → 🚀 Full pipeline: tasks → PRs → staging → main
9.  /release close 1.0.0                    → 🎉 Finalize and close the release

Or go fully autonomous:

/release generate                           → 🗺️ Analyze tasks, propose milestones
/task pick all                              → ⚡ Implement all release tasks in parallel
/release continue 1.0.0 yolo                → 🤖 Run full pipeline autonomously

The plugin supports optional GitHub/GitLab Issues integration that can operate in three modes:

To enable, run /setup and choose your platform when prompted, or manually configure:

cp <plugin-dir>/config/issues-tracker.example.json .claude/issues-tracker.json
# Edit .claude/issues-tracker.json with your repo and settings

The old setup automation and its associated pipeline templates are no longer part of the supported setup surface. Existing historical branches or docs may still mention them, but new projects should use the standard /setup, /task, /docs, and /release flows.

Each task in to-do.txt (or progressing.txt / done.txt) follows this structure:

------------------------------------------------------------------------------
[ ] AUTH-0001 — User Authentication System
------------------------------------------------------------------------------
  Priority: HIGH
  Dependencies: None

  DESCRIPTION:
  Implement user registration, login, and token-based authentication
  using JWT.

  TECHNICAL DETAILS:
  Backend:
    - POST /api/auth/register — validate input, hash password, store user
    - POST /api/auth/login — verify credentials, return JWT

  Files involved:
    CREATE:  src/services/auth.service.ts
    MODIFY:  src/app.ts

Key formatting rules: 78-dash separators, em dash (—) in title, 2-space indent, globally sequential task codes.

codeclaw/
├── .claude-plugin/
│   ├── plugin.json              # 🧩 Plugin manifest
│   └── marketplace.json         # 🏪 Marketplace definition
├── skills/                      # 🛠️ 9 unified Claude Code skills
│   ├── setup/                   # ⚙️ Initialize, configure, scaffold projects
│   ├── update/                  # 🔄 Update CodeClaw-managed files
│   ├── task/                    # 📋 Pick, create, continue, edit, status
│   ├── idea/                    # 💡 Create, approve, disapprove, refactor, scout, edit
│   ├── release/                 # 🚀 Release management (create, generate, continue, close, edit)
│   ├── docs/                    # 📖 Documentation (generate, sync, reset, publish)
│   ├── tests/                   # 🧪 Test coverage analysis and generation
│   ├── help/                    # ❓ Search over skills and documentation
│   └── crazy/                   # 🤖 [BETA] Autonomous project builder
├── scripts/                     # 🐍 Python automation scripts
│   ├── task_manager.py          # Task/idea management CLI
│   ├── release_manager.py       # Release automation CLI
│   ├── docs_manager.py          # Documentation lifecycle CLI
│   ├── skill_helper.py          # Skill dispatch and context resolution
   │   ├── test_manager.py          # Test discovery and gap analysis
   │   ├── ollama_manager.py        # Local model offloading
   │   ├── social_announcer.py      # Release announcement generator
   │   ├── config_lock.py           # Atomic config writes
   │   ├── platform_adapter.py      # Platform abstraction
   │   ├── platform_exporter.py     # Export and sync helpers
   │   ├── platform_utils.py        # Shared platform utilities
   │   ├── quality_gate.py          # Local quality gate
   │   ├── build_portable.py        # Portable archive builder
   │   ├── frontend_wizard.py       # Frontend design wizard
   │   └── build_ccpkg.py           # Package builder
├── templates/                   # 📝 CI/CD workflow templates
├── config/                      # ⚙️ Example configuration files
├── tests/                       # 🧪 Test suite
├── icons/                       # 🎨 Branding assets
├── project-context.md           # 📋 Project guidance
├── AGENTS.md                    # 🧠 Project memory
└── README.md                    # 📖 This file

• 🐍 Python command: All scripts reference python3. On Windows where only python is available, CodeClaw auto-detects the correct command.
• 🔌 Port management: Use lsof/ss on Unix or netstat/taskkill on Windows when you need to inspect open ports.
• 🔍 File search: task_manager.py find-files provides cross-platform file discovery.

# 🔄 Update the plugin
/plugin update claw@dnviti-plugins

# After updating, refresh CodeClaw-managed files in your project
/update

# ⏸️ Disable temporarily
/plugin disable claw@dnviti-plugins

# ▶️ Re-enable
/plugin enable claw@dnviti-plugins

# 🗑️ Uninstall
/plugin uninstall claw@dnviti-plugins

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.